feat(forks): opt-in fork sync for new workflows

apps/docs/content/docs/platform/enterprise/forks.mdx

@@ -57,7 +57,7 @@ Everything under **Copy resources** starts **selected**. That is usually what yo
 Click **Fork**. The child workspace is created immediately. Deployed workflows land as **drafts** in the child. Large content (table rows, knowledge base files, file blobs) may finish copying in the background — watch **Activity** on the source workspace.
 
 <Callout type="info">
-  Only **deployed** workflows are forked. Drafts and undeployed work stay in the parent. If the parent has nothing deployed, the child starts with a blank starter workflow.
+  Only **deployed** workflows are forked, and only the ones that are [synced](#synced-workflows). Drafts and undeployed work stay in the parent. If there is nothing to copy, the child starts with a blank starter workflow.
 </Callout>
 
 ### 3. Open the parent edge (from the child)
@@ -117,16 +117,35 @@ On success you will see a toast such as **Pushed to "…"** or **Pulled from "
 
 ---
 
-## Excluded workflows
+## Synced workflows
 
-The **Excluded workflows** section on the Forks page lists this workspace's deployed workflows in their sidebar folder structure. Check a workflow — or a whole folder at once — to keep it out of forking entirely. Think of it as a `.gitignore` for syncs:
+The **Synced workflows** section on the Forks page lists this workspace's deployed workflows in their sidebar folder structure, each with a checkbox. **Checked means the workflow syncs.** Uncheck one — or a whole folder at once — to keep it out of forking entirely. Think of an unchecked workflow as `.gitignore`d:
 
 - **Never sent** — pushes from this workspace do not carry it, the other side pulling from this workspace does not receive it, and creating a new fork does not copy it
-- **Never touched** — a sync into this workspace will not overwrite or archive it, even if its counterpart was deleted on the other side
+- **Never touched** — a sync into this workspace will not overwrite or archive it, even if its counterpart was deleted on the other side. It stays deployed and keeps serving, and a previously-synced counterpart on the other side keeps running on its last deployed version.
 
-The setting belongs to **this workspace's copy** only. Excluding a workflow here does not exclude its counterpart in the parent or a fork — each workspace manages its own list. If the pair has synced before, the link between them is kept, so un-excluding later resumes updating the same counterpart instead of creating a duplicate.
+The checkbox list belongs to **this workspace's copy** only. Unchecking a workflow here does not unsync its counterpart in the parent or a fork — each workspace manages its own list. If the pair has synced before, the link between them is kept, so re-checking later resumes updating the same counterpart instead of creating a duplicate.
 
-**Example:** a staging fork excludes `Scratch experiment` so it can never reach production, and production excludes `Billing hotfix` so no push from staging can ever overwrite it.
+On the sync page, unsynced workflows still appear in the **Deployed workflows** list, greyed out, with a tooltip naming which workspace they are unsynced in. The sync will not touch them.
+
+**Example:** a staging fork leaves `Scratch experiment` unchecked so it can never reach production, and production leaves `Billing hotfix` unchecked so no push from staging can ever overwrite it.
+
+### Sync new workflows by default
+
+Above the list, **Sync new workflows by default** decides where a **newly created** workflow starts:
+
+| Setting | A new workflow… |
+|---------|-----------------|
+| **On** (default) | joins fork sync — it arrives checked and syncs as soon as you deploy it |
+| **Off** | starts outside fork sync — it arrives unchecked and only syncs after you check it |
+
+Three things to know:
+
+- **It applies to the whole fork lineage.** The toggle writes every workspace in the lineage — the root, every ancestor, every descendant — so a parent and its forks can never disagree about what "new" means. Any workspace admin in the lineage can change it, and each member gets its own audit entry naming the workspace the change came from. A new fork inherits the value at creation.
+- **It is forward-only.** Flipping it never moves an existing workflow in or out of sync. The checkbox list above stays the record of what syncs.
+- **"New" means genuinely new.** Creating, duplicating, or importing a workflow takes this setting, as does the blank starter workflow a fork gets when there is nothing to copy. A workflow that arrives as a **copy** — from a fork, or from a push or pull — inherits its source's own checkbox instead, so a workflow you deliberately synced never lands unsynced in the child.
+
+**Example:** a template workspace turns this off so every scratch workflow the team creates stays local, then checks only the handful meant to reach the forks.
 
 ---
 
@@ -155,6 +174,8 @@ Expand a row for names of workflows and resources that were created, updated, or
 |--------|-----|
 | See Forks / create a fork | Admin on this workspace (+ feature available) |
 | Sync / edit mappings | Admin on **both** sides of the edge |
+| Check / uncheck **Synced workflows** | Admin on the workspace those workflows live in |
+| Change **Sync new workflows by default** | Admin on any one workspace in the lineage — the change applies to every member |
 | Rollback | Admin on the workspace the sync landed in |
 | Disconnect | Admin on **this** side only (you can disconnect even without access to the other workspace) |
 | Open the other workspace | You must be a member of that workspace |
@@ -169,9 +190,9 @@ How each resource behaves at **fork** time vs **sync** time. Use this when you a
 
 | Resource | Fork | Sync |
 |----------|------|------|
-| Deployed workflows | Copied as drafts (unless excluded) | Updated / created / archived (force overwrite) |
+| Deployed workflows | Copied as drafts when [synced](#synced-workflows) | Updated / created / archived (force overwrite) |
 | Undeployed workflows | Not copied | Not synced |
-| [Excluded workflows](#excluded-workflows) | Never | Never — not sent, not overwritten, not archived |
+| [Unsynced workflows](#synced-workflows) | Never | Never — not sent, not overwritten, not archived |
 | Files | Optional copy (default on) | Map or copy |
 | File folders referenced by workflows | Mirrored with their ancestor folders, even when empty | Map by canonical path |
 | Tables | Optional copy (default on) | Map or copy |
@@ -191,11 +212,11 @@ How each resource behaves at **fork** time vs **sync** time. Use this when you a
 
 ### Workflows
 
-Only **deployed** workflows move. Deploy is the commit; sync is the force push/pull of those commits. Workflows marked [excluded](#excluded-workflows) never move in either direction.
+Only **deployed** workflows move, and only the ones checked under [Synced workflows](#synced-workflows). An unsynced workflow never moves in either direction.
 
 | Feature | Behavior |
 |---|----------|
-| **Fork** | Each deployed workflow becomes a **draft** in the child. Run history is not copied. Only folders that contain a copied workflow are kept. |
+| **Fork** | Each synced deployed workflow becomes a **draft** in the child. Run history is not copied. Only folders that contain a copied workflow are kept. |
 | **Sync** | The change list shows what will be updated, created, or archived. The target is overwritten for those workflows. |
 
 **Example:** Parent has `Support triage` deployed and `WIP experiment` as a draft. The fork gets only `Support triage` as a draft. A later push updates the child from the parent’s latest deploy of `Support triage`.
@@ -370,13 +391,16 @@ Schedules, webhooks, and triggers are not live in the child until you **deploy**
 - **Rollback ≠ undo copies** — Workflow versions roll back; copied resources can remain as orphans.
 - **Disconnect is permanent** — You cannot “reconnect” the same edge; you would fork again into a new workspace.
 - **No grandparent sync** — Only the direct parent↔child pair.
+- **The sync default is lineage-wide** — **Sync new workflows by default** is one shared setting for the whole lineage, so changing it from a fork also changes it in the parent and every sibling fork.
 
 ---
 
 <FAQ items={[
   { question: "Why is Sync greyed out?", answer: "Usually a blocking reference, an unmapped credential or secret, or a required dependent field (label, channel, document, …) still empty. Open Blocking sync and the mapping sections — each row explains what to fix. Sync also stays disabled while details are loading or if loading failed (reload the page)." },
   { question: "Is sync a merge?", answer: "No. Deploy is like a commit; sync is a force push or force pull of deployed workflows onto the target. Use Rollback only for the last sync into a workspace, and remember copied resources may remain." },
-  { question: "Who can disconnect a fork I cannot open?", answer: "Any admin on your side of the edge. Disconnect does not require access to the other workspace — so you are not stuck if the other side lost membership." }
+  { question: "Who can disconnect a fork I cannot open?", answer: "Any admin on your side of the edge. Disconnect does not require access to the other workspace — so you are not stuck if the other side lost membership." },
+  { question: "I deployed a new workflow and sync ignored it. Why?", answer: "Sync new workflows by default is off for this fork lineage, so the workflow was created outside fork sync. Open Settings → Organization → Workspace forks and check it under Synced workflows. Turning the toggle back on only affects workflows created after that — it never moves an existing one." },
+  { question: "Does turning Sync new workflows by default off stop my current syncs?", answer: "No. It is forward-only and never rewrites an existing workflow's checkbox, so everything already synced keeps syncing. It also applies to every workspace in the fork lineage, not just the one you changed it from." }
 ]} />
 
 ---

apps/sim/app/api/superuser/import-workflow/route.ts

@@ -18,6 +18,7 @@ import {
 } from '@/lib/workflows/persistence/utils'
 import { sanitizeForExport } from '@/lib/workflows/sanitization/json-sanitizer'
 import { deduplicateWorkflowName } from '@/lib/workflows/utils'
+import { resolveForkSyncExclusionForNewWorkflow } from '@/ee/workspace-forking/lib/sync-default'
 
 const logger = createLogger('SuperUserImportWorkflow')
 
@@ -149,6 +150,9 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       isDeployed: false, // Never copy deployment status
       runCount: 0,
       variables: sourceWorkflow.variables || {},
+      // An imported workflow is a NEW workflow in the target workspace, so it takes that
+      // workspace's fork-sync policy rather than the column default.
+      forkSyncExcluded: await resolveForkSyncExclusionForNewWorkflow(db, targetWorkspaceId),
     })
 
     // Save using existing persistence logic

apps/sim/app/api/v1/admin/workflows/import/route.ts

@@ -41,6 +41,7 @@ import {
   notFoundResponse,
 } from '@/app/api/v1/admin/responses'
 import { extractWorkflowMetadata, type WorkflowImportRequest } from '@/app/api/v1/admin/types'
+import { resolveForkSyncExclusionForNewWorkflow } from '@/ee/workspace-forking/lib/sync-default'
 
 const logger = createLogger('AdminWorkflowImportAPI')
 
@@ -128,6 +129,10 @@ export const POST = withRouteHandler(
         isDeployed: false,
         runCount: 0,
         variables: {},
+        // An imported workflow is a NEW workflow in this workspace, so it takes the
+        // workspace's fork-sync policy. Without this it lands on the column default and
+        // silently joins fork sync in a workspace that opted out.
+        forkSyncExcluded: await resolveForkSyncExclusionForNewWorkflow(db, workspaceId),
       })
 
       /**

apps/sim/app/api/v1/admin/workspaces/[id]/import/route.ts

@@ -62,6 +62,7 @@ import type {
   WorkspaceImportRequest,
   WorkspaceImportResponse,
 } from '@/app/api/v1/admin/types'
+import { resolveForkSyncExclusionForNewWorkflow } from '@/ee/workspace-forking/lib/sync-default'
 
 const logger = createLogger('AdminWorkspaceImportAPI')
 
@@ -363,6 +364,10 @@ async function importSingleWorkflow(
       isDeployed: false,
       runCount: 0,
       variables: {},
+      // An imported workflow is a NEW workflow in this workspace, so it takes the
+      // workspace's fork-sync policy. Without this it lands on the column default and
+      // silently joins fork sync in a workspace that opted out.
+      forkSyncExcluded: await resolveForkSyncExclusionForNewWorkflow(db, workspaceId),
     })
 
     /**

apps/sim/app/api/workspaces/[id]/fork/sync-default/route.ts

@@ -0,0 +1,29 @@
+import { updateForkSyncDefaultContract } from '@/lib/api/contracts/workspace-fork'
+import {
+  defineInternalJsonRoute,
+  internalRateLimits,
+  internalSessionAuth,
+} from '@/lib/api/server/routes'
+import { internalForkErrorPolicy } from '@/ee/workspace-forking/api/route-policies'
+import { forkOperations } from '@/ee/workspace-forking/application/operations'
+import { setForkSyncDefault } from '@/ee/workspace-forking/application/sync-default'
+
+export const PUT = defineInternalJsonRoute({
+  contract: updateForkSyncDefaultContract,
+  auth: internalSessionAuth,
+  operation: forkOperations.syncDefault,
+  /**
+   * Rated, unlike its sibling fork routes. This is the one that writes workspaces the
+   * caller may not administer, under the feature's coarsest advisory lock, so an admin of
+   * any single lineage member could otherwise loop it and starve fork creation across the
+   * whole lineage.
+   */
+  rateLimit: internalRateLimits.user({ bucketName: 'workspace-fork-sync-default' }),
+  errorPolicy: internalForkErrorPolicy,
+  mapInput: ({ params, body }) => ({ workspaceId: params.id, ...body }),
+  present: ({ excludeNewWorkflows, changedWorkspaces }) => ({
+    excludeNewWorkflows,
+    workspacesUpdated: changedWorkspaces.length,
+  }),
+  useCase: setForkSyncDefault,
+})

apps/sim/ee/workspace-forking/application/lineage-details.ts

@@ -4,6 +4,7 @@ import { eq } from 'drizzle-orm'
 import { getEffectiveWorkspacePermission } from '@/lib/workspaces/permissions/utils'
 import { getForkChildren, getForkParent } from '@/ee/workspace-forking/lib/lineage/lineage'
 import { getUndoableRunForTarget } from '@/ee/workspace-forking/lib/promote/promote-run-store'
+import { resolveForkSyncExclusionForNewWorkflow } from '@/ee/workspace-forking/lib/sync-default'
 
 /**
  * Annotates a lineage node with whether the viewer holds any access to it (explicit
@@ -34,10 +35,12 @@ export const getWorkspaceForkLineageDetails = defineForkUseCase({
     context: { userId: string }
   }) {
     const { workspaceId } = input
-    const [rawParent, rawChildren, run] = await Promise.all([
+    const [rawParent, rawChildren, run, forkSyncNewWorkflowsExcluded] = await Promise.all([
       getForkParent(workspaceId),
       getForkChildren(workspaceId),
       getUndoableRunForTarget(db, workspaceId),
+      // Lineage-uniform, so this workspace's own value is the lineage's value.
+      resolveForkSyncExclusionForNewWorkflow(db, workspaceId),
     ])
 
     const [parent, children] = await Promise.all([
@@ -71,6 +74,7 @@ export const getWorkspaceForkLineageDetails = defineForkUseCase({
         createdAt: child.createdAt.toISOString(),
       })),
       undoableRun,
+      forkSyncNewWorkflowsExcluded,
     }
   },
 })

apps/sim/ee/workspace-forking/application/operations.ts

@@ -98,4 +98,20 @@ export const forkOperations = {
     id: 'workspaces.fork.exclusions',
     oauthScope: 'api:write',
   }),
+  /**
+   * Admin on the CALLING workspace is sufficient, and the write then fans out to every
+   * ancestor and descendant, because the default is meaningless unless it is uniform
+   * across a lineage. Flipping it to "sync new workflows" restores the historical
+   * behaviour rather than granting anything new, and it never moves an existing workflow
+   * in or out of sync - so each member records its own audit entry rather than the write
+   * being restricted to one workspace.
+   *
+   * permission-group-exempt: the new-workflow fork-sync default is workspace configuration governed by the admin role.
+   */
+  syncDefault: defineWorkspaceOperation({
+    ...adminPolicy,
+    capability: 'none',
+    id: 'workspaces.fork.sync_default',
+    oauthScope: 'api:write',
+  }),
 } as const

apps/sim/ee/workspace-forking/application/recovery-and-mappings.ts

@@ -52,6 +52,10 @@ export const updateWorkspaceForkMappings = defineForkUseCase<
       input.direction === 'push' ? input.otherWorkspaceId : input.workspaceId
     return db.transaction(async (tx) => {
       await setForkLockTimeout(tx)
+      // Rank 4 - see the rank table on `acquireForkLineageLock`. Unlike promote and
+      // rollback this takes no rank-3 target lock: it rewrites only this edge's mapping
+      // rows, never the target's workflows, so nothing contends with a sync into the
+      // target. Skipping a higher rank is not an ordering violation.
       await acquireForkEdgeLock(tx, edge.childWorkspaceId)
       const [currentEdge] = await tx
         .select({ parentId: workspace.forkedFromWorkspaceId })

apps/sim/ee/workspace-forking/application/revision.ts

@@ -140,7 +140,15 @@ export async function loadForkPreviewRevision(
   }
 }
 
-/** Locks normalized graph rows as well as workflow metadata, including realtime-only writes. */
+/**
+ * Locks normalized graph rows as well as workflow metadata, including realtime-only writes.
+ *
+ * Rank 5 - the heaviest acquirer in the fork module, and the one the rank table on
+ * `acquireForkLineageLock` exists for. It takes `FOR UPDATE` on the `workspace` rows, so
+ * any caller that also needs the rank-2 lineage lock must take that one FIRST; doing it
+ * the other way round deadlocks against `unlinkForkEdge`, which holds the lineage key and
+ * then updates the same `workspace` row.
+ */
 export async function lockForkRevision(tx: DbTransaction, scope: ForkRevisionScope): Promise<void> {
   const workspaceIds = [
     ...new Set([
@@ -199,11 +207,21 @@ export async function assertForkSourceVersions(
   sourceWorkspaceId: string,
   expected: ReadonlyMap<string, { id: string; digest: string }>
 ): Promise<void> {
+  // Verify exactly the workflows that were ADMITTED, rather than re-deriving the source
+  // predicate here. Re-deriving it duplicated `listDeployedWorkflows`'s filter, so the day
+  // a caller admitted a different set - "Copy unsynced workflows" admits sync-excluded
+  // workflows - this query returned fewer rows and every such fork failed on a phantom
+  // size mismatch. Keying off `expected` cannot drift from the admitted set by construction.
+  if (expected.size === 0) return
+  const admittedIds = sql.join(
+    [...expected.keys()].map((id) => sql`${id}`),
+    sql`, `
+  )
   const rows = await tx.execute<{ workflowId: string; id: string; digest: string }>(sql`
     SELECT w.id AS "workflowId", d.id, md5(d.state::text) AS digest FROM ${workflow} w
     JOIN ${workflowDeploymentVersion} d ON d.workflow_id = w.id AND d.is_active = true
     WHERE w.workspace_id = ${sourceWorkspaceId} AND w.is_deployed = true
-      AND w.archived_at IS NULL AND w.fork_sync_excluded = false
+      AND w.archived_at IS NULL AND w.id IN (${admittedIds})
   `)
   if (
     rows.length !== expected.size ||