stagent 0.9.6 → 0.11.0

package/src/lib/chat/tools/workflow-tools.ts

@@ -10,7 +10,8 @@ import {
   workflowDocumentInputs,
 } from "@/lib/db/schema";
 import { eq, and, desc, inArray, like } from "drizzle-orm";
-import { ok, err, type ToolContext } from "./helpers";
+import { ok, err, resolveEntityId, type ToolContext } from "./helpers";
+import { extractKeywords, jaccard } from "@/lib/util/similarity";
 
 const VALID_WORKFLOW_STATUSES = [
   "draft",
@@ -20,6 +21,148 @@ const VALID_WORKFLOW_STATUSES = [
   "failed",
 ] as const;
 
+/**
+ * Minimum weighted-Jaccard score for two workflows to count as "near
+ * duplicates". Combined score = NAME_WEIGHT * nameJaccard +
+ * STEPS_WEIGHT * stepsJaccard.
+ *
+ * Why weighted-and-split rather than a single pooled Jaccard? A pooled
+ * Jaccard over name+step text at threshold 0.7 was flagging legitimate
+ * target-entity variants (e.g. "Enrich contacts" vs "Enrich accounts",
+ * "Daily standup digest" vs "Weekly standup digest") as duplicates,
+ * forcing users to pass `force: true` for every such pair and eroding
+ * trust in the guardrail. Splitting the signal lets the one-token
+ * difference in names AND prompts contribute to two independent
+ * Jaccards, which together pull combined similarity below 0.7 while
+ * structural duplicates (identical steps + near-identical name) still
+ * exceed the threshold.
+ *
+ * Tuning rationale:
+ * - 0.7 threshold preserved from the original implementation.
+ * - 0.5/0.5 weights (no tags). The feature spec sketched a 0.3/0.5/0.2
+ *   split over name/steps/tags, but workflows do not persist tags in
+ *   their definition JSON today. Without a tags signal, 0.5/0.5
+ *   empirically separates legitimate variants (Enrich contacts vs
+ *   accounts: 0.60; Daily vs Weekly standup: 0.68) from structural
+ *   duplicates (identical steps with renamed workflow: 0.75+) with
+ *   headroom on both sides. Revisit weights if tag data lands.
+ *
+ * If a future false-positive case surfaces, add a regression test in
+ * `workflow-tools-dedup.test.ts` → "legitimate variant tolerance" and
+ * re-tune rather than bumping `force: true` everywhere.
+ *
+ * See `features/chat-dedup-variant-tolerance.md`.
+ */
+const WORKFLOW_DEDUP_THRESHOLD = 0.7;
+const WORKFLOW_NAME_WEIGHT = 0.5;
+const WORKFLOW_STEPS_WEIGHT = 0.5;
+
+/**
+ * Split a workflow into its two comparable text signals: the name alone,
+ * and a concatenation of every step's name + prompt. Callers pass each
+ * signal through `extractKeywords` separately so name-level tokens don't
+ * get drowned out by the much larger step-text bag, and vice versa.
+ *
+ * Malformed definition JSON falls back to `stepsText = ""`.
+ */
+function workflowSignals(
+  name: string,
+  definitionJson: string | null
+): { nameText: string; stepsText: string } {
+  if (!definitionJson) return { nameText: name, stepsText: "" };
+  try {
+    const def = JSON.parse(definitionJson);
+    const stepParts: string[] = [];
+    if (Array.isArray(def?.steps)) {
+      for (const step of def.steps) {
+        if (typeof step?.name === "string") stepParts.push(step.name);
+        if (typeof step?.prompt === "string") stepParts.push(step.prompt);
+      }
+    }
+    return { nameText: name, stepsText: stepParts.join(" ") };
+  } catch {
+    return { nameText: name, stepsText: "" };
+  }
+}
+
+export interface SimilarWorkflowMatch {
+  id: string;
+  name: string;
+  similarity: number;
+  reason: string;
+}
+
+/**
+ * Find workflows in the same project that look similar to a candidate.
+ *
+ * Two-tier check:
+ *   1. Exact name match (case-insensitive) → similarity 1.0
+ *   2. Jaccard similarity over extracted keywords from name+step titles+prompts
+ *
+ * Returns up to 3 matches with similarity >= WORKFLOW_DEDUP_THRESHOLD,
+ * sorted by similarity descending. Used by `create_workflow` to warn the
+ * LLM before blindly inserting another row in long conversations where
+ * the sliding-window context builder evicts earlier creations.
+ *
+ * When projectId is null (no active project), returns [] — cross-project
+ * dedup would be misleading, and the handful of null-project rows that
+ * exist aren't worth de-duplicating against each other.
+ */
+export async function findSimilarWorkflows(
+  projectId: string | null,
+  candidateName: string,
+  candidateDefinitionJson: string
+): Promise<SimilarWorkflowMatch[]> {
+  if (!projectId) return [];
+
+  const existing = await db
+    .select({
+      id: workflows.id,
+      name: workflows.name,
+      definition: workflows.definition,
+    })
+    .from(workflows)
+    .where(eq(workflows.projectId, projectId));
+
+  const matches: SimilarWorkflowMatch[] = [];
+  const candidateSignals = workflowSignals(candidateName, candidateDefinitionJson);
+  const candidateNameKeywords = extractKeywords(candidateSignals.nameText);
+  const candidateStepKeywords = extractKeywords(candidateSignals.stepsText);
+  const candidateNameLower = candidateName.trim().toLowerCase();
+
+  for (const row of existing) {
+    // Tier 1: exact name match (case-insensitive)
+    if (row.name.trim().toLowerCase() === candidateNameLower) {
+      matches.push({
+        id: row.id,
+        name: row.name,
+        similarity: 1,
+        reason: `Same name: "${row.name}"`,
+      });
+      continue;
+    }
+
+    // Tier 2: weighted Jaccard — name and step signals scored separately,
+    // then combined with WORKFLOW_NAME_WEIGHT / WORKFLOW_STEPS_WEIGHT so
+    // target-entity variants (same verb, different noun) are not flagged.
+    const existingSignals = workflowSignals(row.name, row.definition);
+    const nameJ = jaccard(candidateNameKeywords, extractKeywords(existingSignals.nameText));
+    const stepsJ = jaccard(candidateStepKeywords, extractKeywords(existingSignals.stepsText));
+    const similarity =
+      WORKFLOW_NAME_WEIGHT * nameJ + WORKFLOW_STEPS_WEIGHT * stepsJ;
+    if (similarity >= WORKFLOW_DEDUP_THRESHOLD) {
+      matches.push({
+        id: row.id,
+        name: row.name,
+        similarity,
+        reason: `Similar content to "${row.name}" (${Math.round(similarity * 100)}%)`,
+      });
+    }
+  }
+
+  return matches.sort((a, b) => b.similarity - a.similarity).slice(0, 3);
+}
+
 export function workflowTools(ctx: ToolContext) {
   return [
     defineTool(
@@ -69,7 +212,7 @@ export function workflowTools(ctx: ToolContext) {
 
     defineTool(
       "create_workflow",
-      "Create a new workflow with a definition. The definition must include a pattern (sequence, parallel, checkpoint, planner-executor, swarm, loop) and steps array.",
+      "Create a new workflow with a definition. The definition must include a pattern (sequence, parallel, checkpoint, planner-executor, swarm, loop) and steps array. Sequence-pattern steps can be either task steps (with prompt + assignedAgent/agentProfile) or delay steps (with delayDuration like '3d', '2h', '30m', '1w') that pause the workflow between tasks — use delay steps for time-distributed sequences (outreach cadences, drip campaigns, cooling periods) rather than creating separate workflows or schedules. IMPORTANT: for the 'run agent on every row of a table' pattern, prefer enrich_table over create_workflow — enrich_table generates the optimal loop configuration, binds each row as {{row.field}} context, wires up the postAction row writeback, and handles idempotent skip of already-populated rows. Hand-rolled equivalents miss these safeguards.",
       {
         name: z.string().min(1).max(200).describe("Workflow name"),
         projectId: z
@@ -79,7 +222,11 @@ export function workflowTools(ctx: ToolContext) {
         definition: z
           .string()
           .describe(
-            'Workflow definition as JSON string. Must include "pattern" and "steps" array. Example: {"pattern":"sequence","steps":[{"id":"step-1","name":"step1","prompt":"Do X","assignedAgent":"claude"}]}'
+            'Workflow definition as JSON string. Must include "pattern" and "steps" array. ' +
+            'Task step example: {"id":"s1","name":"Research","prompt":"Do X","assignedAgent":"claude"}. ' +
+            'Delay step example (sequence pattern only): {"id":"s2","name":"Wait 3 days","delayDuration":"3d"}. ' +
+            'A complete drip sequence: {"pattern":"sequence","steps":[{"id":"s1","name":"Initial","prompt":"Send first email","assignedAgent":"claude"},{"id":"s2","name":"Wait","delayDuration":"3d"},{"id":"s3","name":"Follow-up","prompt":"Send follow-up","assignedAgent":"claude"}]}. ' +
+            'Delay bounds: 1m to 30d. Delay steps must NOT have prompt/profile fields.'
           ),
         documentIds: z
           .array(z.string())
@@ -93,6 +240,12 @@ export function workflowTools(ctx: ToolContext) {
           .describe(
             "Runtime to use for workflow execution (e.g., 'openai-direct', 'anthropic-direct'). Use list_runtimes to see available options. Omit to use the system default."
           ),
+        force: z
+          .boolean()
+          .optional()
+          .describe(
+            "Set to true to bypass the near-duplicate check and always create a new workflow. Only use this when the user has explicitly confirmed they want a second workflow alongside a similar existing one (e.g., 'v2', 'alternate approach'). The dedup check already tolerates target-entity variants (e.g., 'Enrich contacts' vs 'Enrich accounts', 'Daily' vs 'Weekly' standup digest) — so you should NOT pass force=true for those. Default false."
+          ),
       },
       async (args) => {
         try {
@@ -127,6 +280,28 @@ export function workflowTools(ctx: ToolContext) {
           }
 
           const effectiveProjectId = args.projectId ?? ctx.projectId ?? null;
+
+          // Dedup guard: long chat conversations can truncate the earlier
+          // create_workflow tool call out of the sliding-window context, so
+          // the LLM loses its own history and re-creates on "redesign"
+          // requests. Check for near-duplicates in the same project before
+          // inserting. Pass force=true to bypass.
+          if (!args.force) {
+            const similar = await findSimilarWorkflows(
+              effectiveProjectId,
+              args.name,
+              args.definition
+            );
+            if (similar.length > 0) {
+              return ok({
+                status: "similar-found",
+                message:
+                  "Found similar workflow(s) in this project. Use update_workflow to modify an existing one, or pass force=true to create a new workflow alongside them.",
+                matches: similar,
+              });
+            }
+          }
+
           const now = new Date();
           const id = crypto.randomUUID();
 
@@ -211,13 +386,17 @@ export function workflowTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
-          const workflow = await db
+          const resolved = await resolveEntityId(workflows, workflows.id, args.workflowId);
+          if ("error" in resolved) return err(resolved.error);
+          const workflowId = resolved.id;
+
+          const workflow = db
             .select()
             .from(workflows)
-            .where(eq(workflows.id, args.workflowId))
+            .where(eq(workflows.id, workflowId))
             .get();
 
-          if (!workflow) return err(`Workflow not found: ${args.workflowId}`);
+          if (!workflow) return err(`Workflow not found: ${workflowId}`);
 
           const { parseWorkflowState } = await import("@/lib/workflows/engine");
           const { definition, state } = parseWorkflowState(workflow.definition);
@@ -266,13 +445,17 @@ export function workflowTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
-          const existing = await db
+          const resolved = await resolveEntityId(workflows, workflows.id, args.workflowId);
+          if ("error" in resolved) return err(resolved.error);
+          const workflowId = resolved.id;
+
+          const existing = db
             .select()
             .from(workflows)
-            .where(eq(workflows.id, args.workflowId))
+            .where(eq(workflows.id, workflowId))
             .get();
 
-          if (!existing) return err(`Workflow not found: ${args.workflowId}`);
+          if (!existing) return err(`Workflow not found: ${workflowId}`);
           if (existing.status !== "draft")
             return err(`Cannot edit a workflow in '${existing.status}' status. Only draft workflows can be edited.`);
 
@@ -293,12 +476,12 @@ export function workflowTools(ctx: ToolContext) {
           await db
             .update(workflows)
             .set(updates)
-            .where(eq(workflows.id, args.workflowId));
+            .where(eq(workflows.id, workflowId));
 
           const [workflow] = await db
             .select()
             .from(workflows)
-            .where(eq(workflows.id, args.workflowId));
+            .where(eq(workflows.id, workflowId));
 
           ctx.onToolResult?.("update_workflow", workflow);
           return ok({
@@ -321,13 +504,17 @@ export function workflowTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
-          const existing = await db
+          const resolved = await resolveEntityId(workflows, workflows.id, args.workflowId);
+          if ("error" in resolved) return err(resolved.error);
+          const workflowId = resolved.id;
+
+          const existing = db
             .select()
             .from(workflows)
-            .where(eq(workflows.id, args.workflowId))
+            .where(eq(workflows.id, workflowId))
             .get();
 
-          if (!existing) return err(`Workflow not found: ${args.workflowId}`);
+          if (!existing) return err(`Workflow not found: ${workflowId}`);
           if (existing.status === "active")
             return err("Cannot delete an active workflow. Pause or stop it first.");
 
@@ -335,7 +522,7 @@ export function workflowTools(ctx: ToolContext) {
           const childTasks = await db
             .select({ id: tasks.id })
             .from(tasks)
-            .where(eq(tasks.workflowId, args.workflowId));
+            .where(eq(tasks.workflowId, workflowId));
 
           const taskIds = childTasks.map((t) => t.id);
           for (const taskId of taskIds) {
@@ -343,10 +530,10 @@ export function workflowTools(ctx: ToolContext) {
             await db.delete(agentLogs).where(eq(agentLogs.taskId, taskId));
             await db.delete(documents).where(eq(documents.taskId, taskId));
           }
-          await db.delete(tasks).where(eq(tasks.workflowId, args.workflowId));
-          await db.delete(workflows).where(eq(workflows.id, args.workflowId));
+          await db.delete(tasks).where(eq(tasks.workflowId, workflowId));
+          await db.delete(workflows).where(eq(workflows.id, workflowId));
 
-          return ok({ message: "Workflow deleted", workflowId: args.workflowId, name: existing.name });
+          return ok({ message: "Workflow deleted", workflowId, name: existing.name });
         } catch (e) {
           return err(e instanceof Error ? e.message : "Failed to delete workflow");
         }
@@ -361,13 +548,17 @@ export function workflowTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
-          const workflow = await db
+          const resolved = await resolveEntityId(workflows, workflows.id, args.workflowId);
+          if ("error" in resolved) return err(resolved.error);
+          const workflowId = resolved.id;
+
+          const workflow = db
             .select()
             .from(workflows)
-            .where(eq(workflows.id, args.workflowId))
+            .where(eq(workflows.id, workflowId))
             .get();
 
-          if (!workflow) return err(`Workflow not found: ${args.workflowId}`);
+          if (!workflow) return err(`Workflow not found: ${workflowId}`);
 
           // Allow re-execution from crashed "active" if no live tasks
           if (workflow.status === "active") {
@@ -376,7 +567,7 @@ export function workflowTools(ctx: ToolContext) {
               .from(tasks)
               .where(
                 and(
-                  eq(tasks.workflowId, args.workflowId),
+                  eq(tasks.workflowId, workflowId),
                   inArray(tasks.status, ["running", "queued"])
                 )
               );
@@ -404,7 +595,7 @@ export function workflowTools(ctx: ToolContext) {
               .set({ status: "cancelled", updatedAt: new Date() })
               .where(
                 and(
-                  eq(tasks.workflowId, args.workflowId),
+                  eq(tasks.workflowId, workflowId),
                   inArray(tasks.status, ["running", "queued"])
                 )
               );
@@ -419,27 +610,71 @@ export function workflowTools(ctx: ToolContext) {
                 status: "draft",
                 updatedAt: new Date(),
               })
-              .where(eq(workflows.id, args.workflowId));
+              .where(eq(workflows.id, workflowId));
           }
 
           // Atomic claim: set to active
           await db
             .update(workflows)
             .set({ status: "active", updatedAt: new Date() })
-            .where(eq(workflows.id, args.workflowId));
+            .where(eq(workflows.id, workflowId));
 
           // Fire-and-forget
           const { executeWorkflow } = await import("@/lib/workflows/engine");
-          executeWorkflow(args.workflowId).catch(() => {});
+          executeWorkflow(workflowId).catch(() => {});
 
-          ctx.onToolResult?.("execute_workflow", { id: args.workflowId, name: workflow.name });
-          return ok({ message: "Workflow execution started", workflowId: args.workflowId, name: workflow.name });
+          ctx.onToolResult?.("execute_workflow", { id: workflowId, name: workflow.name });
+          return ok({ message: "Workflow execution started", workflowId, name: workflow.name });
         } catch (e) {
           return err(e instanceof Error ? e.message : "Failed to execute workflow");
         }
       }
     ),
 
+    defineTool(
+      "resume_workflow",
+      "Resume a workflow that is paused at a delay step, immediately skipping the remaining delay. Use when the user says 'resume now' or 'skip the wait' for a paused workflow. Only works if the workflow status is 'paused' — a 409 response means the scheduler already resumed it. Requires approval.",
+      {
+        workflowId: z.string().describe("The workflow ID to resume"),
+      },
+      async (args) => {
+        try {
+          const resolved = await resolveEntityId(workflows, workflows.id, args.workflowId);
+          if ("error" in resolved) return err(resolved.error);
+          const workflowId = resolved.id;
+
+          const workflow = db
+            .select()
+            .from(workflows)
+            .where(eq(workflows.id, workflowId))
+            .get();
+
+          if (!workflow) return err(`Workflow not found: ${workflowId}`);
+
+          if (workflow.status !== "paused") {
+            return err(
+              `Workflow is not paused (current status: ${workflow.status}). Only paused workflows can be resumed.`,
+            );
+          }
+
+          const { resumeWorkflow } = await import("@/lib/workflows/engine");
+          // Fire-and-forget: resumeWorkflow performs atomic status transition internally.
+          resumeWorkflow(workflowId).catch((error) => {
+            console.error(`Workflow ${workflowId} resume failed:`, error);
+          });
+
+          ctx.onToolResult?.("resume_workflow", { id: workflowId, name: workflow.name });
+          return ok({
+            message: "Workflow resume dispatched",
+            workflowId,
+            name: workflow.name,
+          });
+        } catch (e) {
+          return err(e instanceof Error ? e.message : "Failed to resume workflow");
+        }
+      },
+    ),
+
     defineTool(
       "get_workflow_status",
       "Get the current execution status of a workflow, including step-by-step progress.",
@@ -448,13 +683,17 @@ export function workflowTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
-          const workflow = await db
+          const resolved = await resolveEntityId(workflows, workflows.id, args.workflowId);
+          if ("error" in resolved) return err(resolved.error);
+          const workflowId = resolved.id;
+
+          const workflow = db
             .select()
             .from(workflows)
-            .where(eq(workflows.id, args.workflowId))
+            .where(eq(workflows.id, workflowId))
             .get();
 
-          if (!workflow) return err(`Workflow not found: ${args.workflowId}`);
+          if (!workflow) return err(`Workflow not found: ${workflowId}`);
 
           const { parseWorkflowState } = await import("@/lib/workflows/engine");
           const { definition, state } = parseWorkflowState(workflow.definition);
@@ -531,11 +770,15 @@ export function workflowTools(ctx: ToolContext) {
           }
 
           if (args.sourceWorkflowId) {
+            const resolvedSrc = await resolveEntityId(workflows, workflows.id, args.sourceWorkflowId);
+            if ("error" in resolvedSrc) return err(resolvedSrc.error);
+            const srcWorkflowId = resolvedSrc.id;
+
             // Find task IDs belonging to the source workflow
             const workflowTasks = await db
               .select({ id: tasks.id })
               .from(tasks)
-              .where(eq(tasks.workflowId, args.sourceWorkflowId));
+              .where(eq(tasks.workflowId, srcWorkflowId));
 
             const taskIds = workflowTasks.map((t) => t.id);
             if (taskIds.length > 0) {

package/src/lib/chat/types.ts

@@ -1,3 +1,9 @@
+import {
+  getRuntimeFeatures,
+  resolveAgentRuntime,
+  type RuntimeFeatures,
+} from "@/lib/agents/runtime/catalog";
+
 /** Screenshot attachment metadata stored in message metadata.attachments */
 export interface ScreenshotAttachment {
   documentId: string;
@@ -107,6 +113,15 @@ export function getRuntimeForModel(modelId: string): string {
   return /^(gpt|o\d)/.test(modelId) ? "openai-codex-app-server" : "claude-code";
 }
 
+/**
+ * Model → LLM-surface features. Thin wrapper around getRuntimeForModel +
+ * getRuntimeFeatures so chat callers don't need to know runtime IDs.
+ */
+export function getFeaturesForModel(modelId: string): RuntimeFeatures {
+  const runtimeId = resolveAgentRuntime(getRuntimeForModel(modelId));
+  return getRuntimeFeatures(runtimeId);
+}
+
 /** Suggested prompt category with expandable sub-prompts */
 export interface PromptCategory {
   id: string;

package/src/lib/constants/settings.ts

@@ -2,8 +2,12 @@ export const SETTINGS_KEYS = {
   AUTH_METHOD: "auth.method",
   AUTH_API_KEY: "auth.apiKey",
   AUTH_API_KEY_SOURCE: "auth.apiKeySource",
+  OPENAI_AUTH_METHOD: "openai.authMethod",
   OPENAI_AUTH_API_KEY: "openai.authApiKey",
   OPENAI_AUTH_API_KEY_SOURCE: "openai.authApiKeySource",
+  OPENAI_AUTH_OAUTH_CONNECTED: "openai.oauthConnected",
+  OPENAI_AUTH_ACCOUNT: "openai.account",
+  OPENAI_AUTH_RATE_LIMITS: "openai.rateLimits",
   PERMISSIONS_ALLOW: "permissions.allow",
   BUDGET_POLICY: "usage.budgetPolicy",
   BUDGET_WARNING_STATE: "usage.budgetWarningState",
@@ -19,24 +23,12 @@ export const SETTINGS_KEYS = {
   ROUTING_PREFERENCE: "routing.preference",
   OLLAMA_BASE_URL: "ollama.baseUrl",
   OLLAMA_DEFAULT_MODEL: "ollama.defaultModel",
-  // License / PLG
-  LICENSE_TIER: "license.tier",
-  LICENSE_EMAIL: "license.email",
-  LICENSE_ACTIVATED_AT: "license.activatedAt",
-  LICENSE_EXPIRES_AT: "license.expiresAt",
-  LICENSE_GRACE_UNTIL: "license.graceUntil",
-  // Supabase cloud
-  SUPABASE_URL: "cloud.supabaseUrl",
-  SUPABASE_ANON_KEY: "cloud.supabaseAnonKey",
-  // Telemetry (opt-in)
-  TELEMETRY_ENABLED: "telemetry.enabled",
-  TELEMETRY_RUNTIME_ID: "telemetry.runtimeId",
-  TELEMETRY_BATCH: "telemetry.batch",
-  // Cloud sync
-  DEVICE_ID: "sync.deviceId",
-  LAST_SYNC_AT: "sync.lastSyncAt",
-  // Stripe
-  STRIPE_CUSTOMER_ID: "billing.stripeCustomerId",
+  // Schedule orchestration
+  SCHEDULE_MAX_CONCURRENT: "schedule.maxConcurrent",
+  SCHEDULE_MAX_RUN_DURATION_SEC: "schedule.maxRunDurationSec",
+  SCHEDULE_CHAT_PRESSURE_DELAY_SEC: "schedule.chatPressureDelaySec",
+  // Environment / profile sync
+  AUTO_PROMOTE_SKILLS: "environment.autoPromoteSkills",
 } as const;
 
 export type RoutingPreference = "cost" | "latency" | "quality" | "manual";

package/src/lib/data/__tests__/clear.test.ts

@@ -2,10 +2,16 @@ import { describe, expect, it } from "vitest";
 import { readFileSync } from "fs";
 import { join } from "path";
 import * as schema from "@/lib/db/schema";
+import { db } from "@/lib/db";
+import { conversations, documents } from "@/lib/db/schema";
+import { clearAllData } from "../clear";
 
 /**
  * Safety-net test: every table exported from schema.ts must appear in clear.ts
- * (except `settings`, which is intentionally preserved across clears).
+ * (except tables in INTENTIONALLY_PRESERVED, which are kept across clears:
+ *  - settings: auth config
+ *  - snapshots: backups, not working data
+ *  - license: paid tier activation — clearing data must not silently downgrade)
  *
  * When you add a new table to schema.ts, this test will fail until you add a
  * corresponding db.delete() call to clear.ts in the correct FK-safe order.
@@ -13,7 +19,7 @@ import * as schema from "@/lib/db/schema";
 describe("clearAllData coverage", () => {
   const INTENTIONALLY_PRESERVED = ["settings", "snapshots"];
 
-  it("deletes every schema table (except settings)", () => {
+  it("deletes every schema table (except preserved ones)", () => {
     const clearSource = readFileSync(
       join(__dirname, "..", "clear.ts"),
       "utf-8"
@@ -40,3 +46,51 @@ describe("clearAllData coverage", () => {
     expect(missing, `Tables missing from clear.ts: ${missing.join(", ")}`).toEqual([]);
   });
 });
+
+/**
+ * FK ordering regression: `documents.conversation_id` references `conversations.id`.
+ * If clearAllData deletes `conversations` before `documents`, SQLite raises
+ * FOREIGN KEY constraint failed. This test seeds a document attached to a
+ * conversation and then calls clearAllData to ensure the ordering holds.
+ *
+ * Incident: the stagent-growth domain clone (2026-04-07) hit this because its
+ * seeded data included chat-attached documents.
+ */
+describe("clearAllData FK ordering", () => {
+  it("clears a conversation that has an attached document without FK violation", () => {
+    const now = new Date();
+    const conversationId = "test-conv-fk-ordering";
+    const documentId = "test-doc-fk-ordering";
+
+    db.insert(conversations)
+      .values({
+        id: conversationId,
+        runtimeId: "test-runtime",
+        status: "active",
+        createdAt: now,
+        updatedAt: now,
+      })
+      .run();
+
+    db.insert(documents)
+      .values({
+        id: documentId,
+        filename: "fk-ordering-test.txt",
+        originalName: "fk-ordering-test.txt",
+        mimeType: "text/plain",
+        size: 10,
+        storagePath: "/tmp/fk-ordering-test.txt",
+        conversationId,
+        createdAt: now,
+        updatedAt: now,
+      })
+      .run();
+
+    expect(() => clearAllData()).not.toThrow();
+
+    const remainingConvs = db.select().from(conversations).all();
+    const remainingDocs = db.select().from(documents).all();
+    expect(remainingConvs).toHaveLength(0);
+    expect(remainingDocs).toHaveLength(0);
+  });
+});