From 1bf1b851b0ada8c714d4aca5976df706022ddfd3 Mon Sep 17 00:00:00 2001
From: Waleed <walif6@gmail.com>
Date: Fri, 6 Nov 2026 12:07:57 -0800
Subject: [PATCH 1/3] fix(billing): refuse Stripe checkout for AWS
 Marketplace-billed customers (#9748)

* fix(billing): refuse Stripe checkout for AWS Marketplace-billed customers

AWS bills a Marketplace customer, and AWS's SaaS guidelines require a listed
product to be billed entirely through its Marketplace dimensions. A
Marketplace-billed organization or account looks Free to Stripe, so a
Stripe checkout would start a second, real subscription. Until now only a
client gate stood in the way, and it failed open: a failed license lookup
reported "not Marketplace-billed" and showed Stripe plans, with no retry
short of a reload.

Server: authorizeSubscriptionReference (organization references) and
assertPersonalCheckoutAllowed (personal references) now refuse an upgrade
with 409 when the reference holds a Marketplace license that is not
inactive, only where AWS_MARKETPLACE_PRODUCT_CODE is set. The personal
check lives in assertPersonalCheckoutAllowed because the Better Auth Stripe
plugin never calls authorizeReference for a personal reference, so a check
there would never run for one. Other actions, and staff Enterprise
provisioning, are unaffected.

Client: useAwsMarketplaceBilling exposes isResolved, isError, isRetrying
and retry, and an unknown billing state now gates plan changes. The billing
page hides "Explore plans" until the lookup resolves; the upgrade page
shows "Workspace plans unavailable" with a "Try again" chip when the lookup
fails.

* fix(billing): keep the Marketplace lookup retry stable across renders
---
 .../settings/components/billing/billing.tsx   |   2 +-
 .../upgrade/hooks/use-upgrade-state.ts        |   9 +-
 .../[workspaceId]/upgrade/upgrade.tsx         |  20 ++-
 .../hooks/queries/aws-marketplace.test.tsx    |  74 ++++++++
 apps/sim/hooks/queries/aws-marketplace.ts     |  14 +-
 apps/sim/lib/billing/authorization.ts         |  31 +++-
 .../checkout-guard.integration.ts             | 168 ++++++++++++++++++
 .../lib/billing/aws-marketplace/repository.ts |  24 +++
 8 files changed, 331 insertions(+), 11 deletions(-)
 create mode 100644 apps/sim/hooks/queries/aws-marketplace.test.tsx
 create mode 100644 apps/sim/lib/billing/aws-marketplace/checkout-guard.integration.ts

diff --git a/apps/sim/app/workspace/[workspaceId]/settings/components/billing/billing.tsx b/apps/sim/app/workspace/[workspaceId]/settings/components/billing/billing.tsx
index d0fbd308b03..0105c89b89d 100644
--- a/apps/sim/app/workspace/[workspaceId]/settings/components/billing/billing.tsx
+++ b/apps/sim/app/workspace/[workspaceId]/settings/components/billing/billing.tsx
@@ -521,8 +521,8 @@ export function Billing({ scope, organizationId, creditUsageHref }: BillingProps
           </div>
         </div>
         {!subscription.isEnterprise &&
+          marketplaceBilling.isResolved &&
           !billedThroughMarketplace &&
-          !marketplaceBilling.isPending &&
           (canExplorePlans && upgradeHref ? (
             <ChipLink
               href={upgradeHref}
diff --git a/apps/sim/app/workspace/[workspaceId]/upgrade/hooks/use-upgrade-state.ts b/apps/sim/app/workspace/[workspaceId]/upgrade/hooks/use-upgrade-state.ts
index b612e8b6a3c..6b44cbff1b8 100644
--- a/apps/sim/app/workspace/[workspaceId]/upgrade/hooks/use-upgrade-state.ts
+++ b/apps/sim/app/workspace/[workspaceId]/upgrade/hooks/use-upgrade-state.ts
@@ -40,6 +40,10 @@ export interface UpgradeState {
   }
   showUpgradePlans: boolean
   billedThroughMarketplace: boolean
+  /** How this workspace is billed could not be read, so plans stay hidden until a retry succeeds. */
+  billingLookupFailed: boolean
+  isRetryingBillingLookup: boolean
+  retryBillingLookup: () => void
   proTier: { credits: number; dollars: number; name: string }
   maxTier: { credits: number; dollars: number; name: string }
   isOnPro: boolean
@@ -201,8 +205,11 @@ export function useUpgradeState({
     setIsAnnual,
     subscription,
     showUpgradePlans:
-      !subscription.isEnterprise && !marketplace.isPending && !marketplace.billedThroughMarketplace,
+      !subscription.isEnterprise && marketplace.isResolved && !marketplace.billedThroughMarketplace,
     billedThroughMarketplace: marketplace.billedThroughMarketplace,
+    billingLookupFailed: !marketplace.isResolved && marketplace.isError,
+    isRetryingBillingLookup: marketplace.isRetrying,
+    retryBillingLookup: marketplace.retry,
     proTier: PRO_TIER,
     maxTier: MAX_TIER,
     isOnPro,
diff --git a/apps/sim/app/workspace/[workspaceId]/upgrade/upgrade.tsx b/apps/sim/app/workspace/[workspaceId]/upgrade/upgrade.tsx
index 8f4945ab453..62c3a20e58f 100644
--- a/apps/sim/app/workspace/[workspaceId]/upgrade/upgrade.tsx
+++ b/apps/sim/app/workspace/[workspaceId]/upgrade/upgrade.tsx
@@ -85,12 +85,15 @@ export function Upgrade({ workspaceId }: UpgradeProps) {
     return null
   }
 
-  if (!canManageBilling || state.billedThroughMarketplace) {
-    const description = canManageBilling
-      ? 'Your subscription is billed through AWS Marketplace, so plans can’t be changed here.'
-      : hostContext.hostOrganizationId
+  if (!canManageBilling || state.billedThroughMarketplace || state.billingLookupFailed) {
+    const description = !canManageBilling
+      ? hostContext.hostOrganizationId
         ? `Plans for ${hostContext.workspace.name} are managed by its organization administrators. Contact an organization admin to change this workspace’s plan.`
         : `Only the owner of ${hostContext.workspace.name} can change this workspace’s plan.`
+      : state.billedThroughMarketplace
+        ? 'Your subscription is billed through AWS Marketplace, so plans can’t be changed here.'
+        : 'We couldn’t confirm how this workspace is billed.'
+    const canRetryLookup = canManageBilling && state.billingLookupFailed
 
     return (
       <div className='flex h-full flex-col bg-[var(--bg)]'>
@@ -103,6 +106,15 @@ export function Upgrade({ workspaceId }: UpgradeProps) {
           <div className='flex max-w-md flex-col items-center gap-3 text-center'>
             <h1 className='text-[var(--text-body)] text-lg'>Workspace plans unavailable</h1>
             <p className='text-[var(--text-muted)] text-sm'>{description}</p>
+            {canRetryLookup && (
+              <Chip
+                variant='border'
+                disabled={state.isRetryingBillingLookup}
+                onClick={state.retryBillingLookup}
+              >
+                {state.isRetryingBillingLookup ? 'Retrying…' : 'Try again'}
+              </Chip>
+            )}
           </div>
         </div>
       </div>
diff --git a/apps/sim/hooks/queries/aws-marketplace.test.tsx b/apps/sim/hooks/queries/aws-marketplace.test.tsx
new file mode 100644
index 00000000000..68ab8b89a30
--- /dev/null
+++ b/apps/sim/hooks/queries/aws-marketplace.test.tsx
@@ -0,0 +1,74 @@
+/** @vitest-environment jsdom */
+
+import { act } from 'react'
+import {
+  apiClientRequestMock,
+  apiClientRequestMockFns,
+} from '@sim/testing/mocks/api-client-request.mock'
+import { authClientMock } from '@sim/testing/mocks/auth-client.mock'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('@/lib/api/client/request', () => apiClientRequestMock)
+vi.mock('@/lib/auth/client', () => authClientMock)
+
+import { useAwsMarketplaceBilling } from '@/hooks/queries/aws-marketplace'
+
+const mockRequestJson = apiClientRequestMockFns.mockRequestJson
+
+let root: Root | null = null
+let billing: ReturnType<typeof useAwsMarketplaceBilling> | undefined
+
+function Probe() {
+  billing = useAwsMarketplaceBilling('org-1')
+  return null
+}
+
+function render() {
+  ;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+  const container = document.createElement('div')
+  document.body.appendChild(container)
+  root = createRoot(container)
+  act(() => {
+    root?.render(
+      <QueryClientProvider client={queryClient}>
+        <Probe />
+      </QueryClientProvider>
+    )
+  })
+}
+
+async function settled(assertion: () => void) {
+  await act(async () => {
+    await vi.waitFor(assertion, { interval: 1, timeout: 2_000 })
+  })
+}
+
+afterEach(() => {
+  act(() => root?.unmount())
+  root = null
+  billing = undefined
+  document.body.replaceChildren()
+})
+
+describe('useAwsMarketplaceBilling', () => {
+  it('stays unresolved when the license lookup fails, so plan changes stay gated', async () => {
+    mockRequestJson.mockRejectedValueOnce(new Error('lookup failed'))
+    render()
+
+    await settled(() => expect(billing?.isError).toBe(true))
+    expect(billing?.isResolved).toBe(false)
+    expect(billing?.billedThroughMarketplace).toBe(false)
+  })
+
+  it('resolves to not Marketplace-billed when the scope holds no license', async () => {
+    mockRequestJson.mockResolvedValueOnce({ licenses: [] })
+    render()
+
+    await settled(() => expect(billing?.isResolved).toBe(true))
+    expect(billing?.billedThroughMarketplace).toBe(false)
+    expect(billing?.isError).toBe(false)
+  })
+})
diff --git a/apps/sim/hooks/queries/aws-marketplace.ts b/apps/sim/hooks/queries/aws-marketplace.ts
index 39e06715b1d..ef5fa54fe05 100644
--- a/apps/sim/hooks/queries/aws-marketplace.ts
+++ b/apps/sim/hooks/queries/aws-marketplace.ts
@@ -1,3 +1,4 @@
+import { useCallback } from 'react'
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
 import { requestJson } from '@/lib/api/client/request'
 import type { ContractBodyInput } from '@/lib/api/contracts'
@@ -70,12 +71,21 @@ export function useSaveAwsMarketplaceClaimContact() {
 
 /**
  * Whether AWS Marketplace bills this scope: the organization, or with null the viewer's account.
- * A failed read reports false, so a lookup error never blocks a customer who pays through Stripe.
+ * Until `isResolved`, how the scope is billed is unknown, and an unknown state gates plan changes
+ * the same as Marketplace billing does: a failed lookup must not open Stripe checkout to a
+ * customer AWS bills. `retry` reads it again.
  */
 export function useAwsMarketplaceBilling(organizationId: string | null) {
   const licenses = useAwsMarketplaceLicenses(organizationId)
+  const { refetch } = licenses
+  const retry = useCallback(() => {
+    void refetch()
+  }, [refetch])
   return {
-    isPending: licenses.isPending,
+    isResolved: licenses.data !== undefined,
+    isError: licenses.isError,
+    isRetrying: licenses.isFetching,
+    retry,
     billedThroughMarketplace:
       licenses.data?.some((license) => license.status !== 'inactive') ?? false,
   }
diff --git a/apps/sim/lib/billing/authorization.ts b/apps/sim/lib/billing/authorization.ts
index 5ac970bb40d..da71750cd50 100644
--- a/apps/sim/lib/billing/authorization.ts
+++ b/apps/sim/lib/billing/authorization.ts
@@ -3,6 +3,8 @@ import { subscription } from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
 import { APIError } from 'better-auth/api'
 import { and, eq, isNotNull } from 'drizzle-orm'
+import { getAwsMarketplaceProductCode } from '@/lib/billing/aws-marketplace/config'
+import { holdsMarketplaceLicense } from '@/lib/billing/aws-marketplace/repository'
 import { isOrganizationOwnerOrAdmin } from '@/lib/billing/core/organization'
 import {
   getOrganizationCoverageForMember,
@@ -55,6 +57,22 @@ async function assertNoBoundIncompleteSubscription(referenceId: string): Promise
   })
 }
 
+/**
+ * Refuse a Stripe checkout for a reference AWS Marketplace bills. A listed product must be billed
+ * entirely through AWS, and such a customer looks Free to Stripe, so a checkout would start a
+ * second, real subscription. The client hides plans too, but only this check holds when its
+ * license lookup fails.
+ */
+async function assertNotBilledThroughMarketplace(referenceId: string): Promise<void> {
+  if (!getAwsMarketplaceProductCode()) return
+  if (!(await holdsMarketplaceLicense(referenceId))) return
+
+  logger.warn('Blocking checkout - reference is billed through AWS Marketplace', { referenceId })
+  throw new APIError('CONFLICT', {
+    message: 'This subscription is billed through AWS Marketplace. Contact support to change it.',
+  })
+}
+
 /**
  * Classify a `/subscription/upgrade` request as a personal checkout using
  * the same reference resolution as the Better Auth Stripe plugin
@@ -81,9 +99,10 @@ export function isPersonalCheckoutRequest(
 /**
  * Guard for personal (user-referenced) checkouts on `/subscription/upgrade`.
  *
- * Blocks both a bound, incomplete Stripe subscription and a member already
- * covered by an entitled organization subscription. Throws {@link APIError}
- * with a user-facing message; the checkout UI surfaces it as-is.
+ * Blocks an account AWS Marketplace bills, a bound, incomplete Stripe
+ * subscription, and a member already covered by an entitled organization
+ * subscription. Throws {@link APIError} with a user-facing message; the
+ * checkout UI surfaces it as-is.
  *
  * Called from the Better Auth `hooks.before` middleware, NOT from
  * `authorizeReference`: the Stripe plugin skips `authorizeReference`
@@ -94,6 +113,7 @@ export function isPersonalCheckoutRequest(
  * rejected rather than risking a duplicate subscription.
  */
 export async function assertPersonalCheckoutAllowed(userId: string): Promise<void> {
+  await assertNotBilledThroughMarketplace(userId)
   await assertNoBoundIncompleteSubscription(userId)
 
   const coverage = await getOrganizationCoverageForMember(userId)
@@ -130,6 +150,7 @@ export async function assertPersonalCheckoutAllowed(userId: string): Promise<voi
  * For `upgrade-subscription` (checkout) this enforces, each thrown as an
  * {@link APIError} with a descriptive message so callers see the real
  * reason instead of a generic "Unauthorized":
+ * - An organization AWS Marketplace bills cannot check out through Stripe.
  * - Organizations can only check out Team or Enterprise plans — a `pro_*`
  *   plan can never become org-referenced.
  * - A bound, incomplete Stripe subscription must finish before another
@@ -148,6 +169,10 @@ export async function authorizeSubscriptionReference(
     return true
   }
 
+  if (action === 'upgrade-subscription') {
+    await assertNotBilledThroughMarketplace(referenceId)
+  }
+
   if (action === 'upgrade-subscription' && !isOrgPlan(plan)) {
     logger.warn('Blocking checkout - organizations can only subscribe to Team or Enterprise', {
       userId,
diff --git a/apps/sim/lib/billing/aws-marketplace/checkout-guard.integration.ts b/apps/sim/lib/billing/aws-marketplace/checkout-guard.integration.ts
new file mode 100644
index 00000000000..4a7ff2aeaa5
--- /dev/null
+++ b/apps/sim/lib/billing/aws-marketplace/checkout-guard.integration.ts
@@ -0,0 +1,168 @@
+import { db } from '@sim/db'
+import { awsMarketplaceLicense, member, organization, user } from '@sim/db/schema'
+import { generateId } from '@sim/utils/id'
+import { inArray } from 'drizzle-orm'
+import { afterAll, afterEach, describe, expect, it, vi } from 'vitest'
+
+const PRODUCT = 'product-placeholder'
+const ACCOUNT = '000000000000'
+const TEAM_PLAN = 'team_6000'
+
+const productCode = vi.hoisted(() => ({ current: 'product-placeholder' as string | null }))
+
+vi.mock('@/lib/billing/aws-marketplace/config', () => ({
+  getAwsMarketplaceProductCode: () => productCode.current,
+}))
+
+import {
+  assertPersonalCheckoutAllowed,
+  authorizeSubscriptionReference,
+} from '@/lib/billing/authorization'
+
+type LicenseStatus = (typeof awsMarketplaceLicense.$inferInsert)['status']
+
+const MARKETPLACE_REFUSAL = /billed through AWS Marketplace/
+
+const userIds: string[] = []
+const organizationIds: string[] = []
+
+async function createUser(): Promise<string> {
+  const id = generateId()
+  userIds.push(id)
+  await db.insert(user).values({
+    id,
+    name: 'Checkout guard fixture',
+    email: `${id}@example.test`,
+    emailVerified: true,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  })
+  return id
+}
+
+/** An organization `ownerId` owns, so every check but the one under test admits the checkout. */
+async function createOwnedOrganization(ownerId: string): Promise<string> {
+  const id = generateId()
+  organizationIds.push(id)
+  await db
+    .insert(organization)
+    .values({ id, name: 'Checkout guard org', slug: id, createdAt: new Date() })
+  await db.insert(member).values({
+    id: generateId(),
+    organizationId: id,
+    userId: ownerId,
+    role: 'owner',
+    createdAt: new Date(),
+  })
+  return id
+}
+
+async function insertLicense(link: {
+  organizationId: string | null
+  linkedByUserId: string
+  status: LicenseStatus
+}) {
+  const now = new Date()
+  await db.insert(awsMarketplaceLicense).values({
+    id: generateId(),
+    licenseArn: `license-${generateId()}`,
+    productCode: PRODUCT,
+    customerAwsAccountId: ACCOUNT,
+    dimension: 'enterprise',
+    quantity: 25,
+    lastVerifiedAt: now,
+    lastVerificationAttemptAt: now,
+    ...link,
+  })
+}
+
+async function organizationWithLicense(status: LicenseStatus | null) {
+  const ownerId = await createUser()
+  const organizationId = await createOwnedOrganization(ownerId)
+  if (status) await insertLicense({ organizationId, linkedByUserId: ownerId, status })
+  return { ownerId, organizationId }
+}
+
+afterEach(() => {
+  productCode.current = PRODUCT
+})
+
+afterAll(async () => {
+  if (organizationIds.length) {
+    await db
+      .delete(awsMarketplaceLicense)
+      .where(inArray(awsMarketplaceLicense.organizationId, organizationIds))
+    await db.delete(organization).where(inArray(organization.id, organizationIds))
+  }
+  if (userIds.length) {
+    await db
+      .delete(awsMarketplaceLicense)
+      .where(inArray(awsMarketplaceLicense.linkedByUserId, userIds))
+    await db.delete(user).where(inArray(user.id, userIds))
+  }
+})
+
+describe('Stripe checkout for an AWS Marketplace-billed reference', () => {
+  it.each(['pending', 'active'] as const)(
+    'refuses an organization whose license is %s',
+    async (status) => {
+      const { ownerId, organizationId } = await organizationWithLicense(status)
+
+      await expect(
+        authorizeSubscriptionReference(ownerId, organizationId, 'upgrade-subscription', TEAM_PLAN)
+      ).rejects.toMatchObject({
+        statusCode: 409,
+        message: expect.stringMatching(MARKETPLACE_REFUSAL),
+      })
+    }
+  )
+
+  it('refuses a personal checkout for a user whose account holds a license', async () => {
+    const userId = await createUser()
+    await insertLicense({ organizationId: null, linkedByUserId: userId, status: 'active' })
+
+    await expect(assertPersonalCheckoutAllowed(userId)).rejects.toMatchObject({
+      statusCode: 409,
+      message: expect.stringMatching(MARKETPLACE_REFUSAL),
+    })
+  })
+
+  it('allows an organization whose license is inactive', async () => {
+    const { ownerId, organizationId } = await organizationWithLicense('inactive')
+
+    await expect(
+      authorizeSubscriptionReference(ownerId, organizationId, 'upgrade-subscription', TEAM_PLAN)
+    ).resolves.toBe(true)
+  })
+
+  it('allows an organization with no license', async () => {
+    const { ownerId, organizationId } = await organizationWithLicense(null)
+
+    await expect(
+      authorizeSubscriptionReference(ownerId, organizationId, 'upgrade-subscription', TEAM_PLAN)
+    ).resolves.toBe(true)
+  })
+
+  it('allows a licensed organization and account where Sim does not sell on AWS', async () => {
+    const { ownerId, organizationId } = await organizationWithLicense('active')
+    const userId = await createUser()
+    await insertLicense({ organizationId: null, linkedByUserId: userId, status: 'active' })
+    productCode.current = null
+
+    await expect(
+      authorizeSubscriptionReference(ownerId, organizationId, 'upgrade-subscription', TEAM_PLAN)
+    ).resolves.toBe(true)
+    await expect(assertPersonalCheckoutAllowed(userId)).resolves.toBeUndefined()
+  })
+
+  it.each(['billing-portal', 'cancel-subscription', 'list-subscription'])(
+    'still allows %s for a licensed organization',
+    async (action) => {
+      const { ownerId, organizationId } = await organizationWithLicense('active')
+
+      await expect(authorizeSubscriptionReference(ownerId, organizationId, action)).resolves.toBe(
+        true
+      )
+    }
+  )
+})
diff --git a/apps/sim/lib/billing/aws-marketplace/repository.ts b/apps/sim/lib/billing/aws-marketplace/repository.ts
index 1b5d1425c1c..0b3a8ff2ef4 100644
--- a/apps/sim/lib/billing/aws-marketplace/repository.ts
+++ b/apps/sim/lib/billing/aws-marketplace/repository.ts
@@ -612,6 +612,30 @@ export async function listAccountLicenses(userId: string) {
     .orderBy(asc(awsMarketplaceLicense.createdAt))
 }
 
+/**
+ * Whether AWS Marketplace bills this billing reference: a license that is not inactive, linked to
+ * the organization, or registered to the user's account with no organization yet.
+ */
+export async function holdsMarketplaceLicense(referenceId: string): Promise<boolean> {
+  const [row] = await db
+    .select({ id: awsMarketplaceLicense.id })
+    .from(awsMarketplaceLicense)
+    .where(
+      and(
+        ne(awsMarketplaceLicense.status, 'inactive'),
+        or(
+          eq(awsMarketplaceLicense.organizationId, referenceId),
+          and(
+            isNull(awsMarketplaceLicense.organizationId),
+            eq(awsMarketplaceLicense.linkedByUserId, referenceId)
+          )
+        )
+      )
+    )
+    .limit(1)
+  return Boolean(row)
+}
+
 /**
  * Licenses with no organization, newest first, for the admin dashboard: those waiting for the team
  * to link them, and inactive ones that never will be.

From 89c1d63e27b981ffee04993ecf5d8748c98fbee2 Mon Sep 17 00:00:00 2001
From: Waleed <walif6@gmail.com>
Date: Fri, 6 Nov 2026 12:13:04 -0800
Subject: [PATCH 2/3] fix(mothership): answer a Chat workflow tool paused for a
 person with its resume link (#9751)

* fix(mothership): answer a Chat workflow tool paused for a person with its resume link

A browser-run workflow tool whose run paused at a Human in the Loop block was
never answered: the browser reports nothing for a paused run, the execute
route's report skipped a non-terminal log, and the lapsed-wait watcher only
detaches a running log. The Chat turn parked on the call until it timed out,
and the model never learned the run was waiting on the user or where to answer.

- Settle the call when its run waits on a person, with the resume page link
  and an instruction to hand it to the user rather than resume it. A run
  paused only on time resumes itself and keeps the call held.
- The Chat-side waiter re-reads the pause and the call's binding instead of
  trusting a confirmation's data.
- The lapsed-wait watcher answers a human pause if the route's report failed.
- Share the pause point parser between run status reads and this check.

* fix(mothership): answer a paused Chat workflow tool still running when its form was submitted before Chat read the pause
---
 .../lib/mothership/request/tools/client.ts    |  46 ++++-
 .../request/tools/workflow-client-fallback.ts |  11 ++
 .../workflow-client-settlement.integration.ts | 165 +++++++++++++++++-
 .../tools/workflow-client-settlement.ts       |  92 +++++++---
 .../lib/mothership/tools/workflow-tools.ts    |  27 +++
 .../lib/workflows/executor/execution-state.ts |  40 ++++-
 .../workflows/executor/execution-status.ts    |   8 +-
 7 files changed, 347 insertions(+), 42 deletions(-)

diff --git a/apps/sim/lib/mothership/request/tools/client.ts b/apps/sim/lib/mothership/request/tools/client.ts
index 9c730c16e6f..7d0c2568816 100644
--- a/apps/sim/lib/mothership/request/tools/client.ts
+++ b/apps/sim/lib/mothership/request/tools/client.ts
@@ -6,6 +6,7 @@ import {
   type AsyncTerminalCompletionSnapshot,
   getTerminalConfirmationStatus,
   isAsyncTerminalConfirmationStatus,
+  isTerminalAsyncStatus,
 } from '@/lib/mothership/async-runs/lifecycle'
 import { replaceTerminalAsyncToolCallResult } from '@/lib/mothership/async-runs/repository'
 import { MothershipStreamV1ToolOutcome } from '@/lib/mothership/generated/mothership-stream-v1'
@@ -30,13 +31,20 @@ import {
   presentWorkflowLogsForModel,
 } from '@/lib/mothership/tools/workflow-output'
 import {
+  buildPausedWorkflowToolCompletion,
   createStructuralWorkflowToolCompletionData,
   getWorkflowToolCompletionExecutionId,
   getWorkflowToolCompletionMessage,
   getWorkflowToolLaunchError,
+  WORKFLOW_TOOL_PAUSED_STATUS,
   type WorkflowToolLaunchError,
 } from '@/lib/mothership/tools/workflow-tools'
-import { getTrustedWorkflowToolExecution } from '@/lib/workflows/executor/execution-state'
+import {
+  getHumanPauseResumeUrl,
+  getTrustedWorkflowToolExecution,
+  getWorkflowExecutionCopilotToolCallId,
+  getWorkflowExecutionLogStatus,
+} from '@/lib/workflows/executor/execution-state'
 import type { ResolvedSecretTraceRegistry } from '@/executor/utils/resolved-secret-trace-registry'
 
 const logger = createLogger('CopilotClientToolWaiter')
@@ -364,6 +372,42 @@ export async function waitForWorkflowToolCompletion({
       return structuralWorkflowCompletion(structuralStatus, workflowId, executionId, launchError)
     }
 
+    if (
+      completion.status === MothershipStreamV1ToolOutcome.success &&
+      isPlainRecord(completion.data) &&
+      completion.data.status === WORKFLOW_TOOL_PAUSED_STATUS
+    ) {
+      // Re-read rather than trust the confirmation; a run resumed since then reads as finished.
+      const [resumeUrl, boundToolCallId, logStatus] = await Promise.all([
+        getHumanPauseResumeUrl(executionId, workflowId),
+        getWorkflowExecutionCopilotToolCallId(executionId, workflowId),
+        getWorkflowExecutionLogStatus(executionId, workflowId),
+      ]).catch((error) => {
+        logger.warn('Failed to read paused workflow tool execution', {
+          toolCallId,
+          workflowId,
+          executionId,
+          error: getErrorMessage(error),
+        })
+        return [null, undefined, undefined] as const
+      })
+      if (boundToolCallId === toolCallId) {
+        if (resumeUrl) {
+          toolRegistry?.markIncomplete('client-tool-completion-deferred')
+          return buildPausedWorkflowToolCompletion(workflowId, executionId, resumeUrl)
+        }
+        // The person answered before this read and the resumed run has no result yet.
+        if (logStatus !== undefined && !isTerminalAsyncStatus(logStatus)) {
+          toolRegistry?.markIncomplete('client-tool-completion-deferred')
+          return structuralWorkflowCompletion(
+            ASYNC_TOOL_CONFIRMATION_STATUS.background,
+            workflowId,
+            executionId
+          )
+        }
+      }
+    }
+
     try {
       trustedExecution = await getTrustedWorkflowToolExecution(executionId, workflowId, toolCallId)
     } catch (error) {
diff --git a/apps/sim/lib/mothership/request/tools/workflow-client-fallback.ts b/apps/sim/lib/mothership/request/tools/workflow-client-fallback.ts
index 3503ab696d0..8fffd112a91 100644
--- a/apps/sim/lib/mothership/request/tools/workflow-client-fallback.ts
+++ b/apps/sim/lib/mothership/request/tools/workflow-client-fallback.ts
@@ -20,6 +20,7 @@ import { recordDegraded } from '@/lib/mothership/request/metrics'
 import { waitForWorkflowToolCompletion } from '@/lib/mothership/request/tools/client'
 import { settleClientToolCall } from '@/lib/mothership/request/tools/client-settlement.server'
 import { toolStartWindowClosed } from '@/lib/mothership/request/tools/deadline'
+import { reportPausedClientWorkflowTool } from '@/lib/mothership/request/tools/workflow-client-settlement'
 import {
   createStructuralWorkflowToolCompletionData,
   getWorkflowToolCompletionMessage,
@@ -98,6 +99,16 @@ async function detachClientRunAfterWait(params: {
     const logged = await getWorkflowExecutionLogStatus(executionId, workflowId).catch(
       () => undefined
     )
+    // A paused run's log stays `pending`. The execute route answers a run waiting on a person;
+    // this covers that best-effort report failing.
+    if (logged === 'pending') {
+      const answered = await reportPausedClientWorkflowTool({
+        toolCallId,
+        executionId,
+        workflowId,
+      }).catch(() => false)
+      if (answered) return
+    }
     if (logged !== 'running') continue
     const status = ASYNC_TOOL_CONFIRMATION_STATUS.background
     const settled = await settleClientToolCall({
diff --git a/apps/sim/lib/mothership/request/tools/workflow-client-settlement.integration.ts b/apps/sim/lib/mothership/request/tools/workflow-client-settlement.integration.ts
index 5f35f02f68b..1f675be2a67 100644
--- a/apps/sim/lib/mothership/request/tools/workflow-client-settlement.integration.ts
+++ b/apps/sim/lib/mothership/request/tools/workflow-client-settlement.integration.ts
@@ -42,7 +42,10 @@ import {
   settleClientWorkflowToolExecution,
   upsertAsyncToolCall,
 } from '@/lib/mothership/async-runs/repository'
-import { getToolConfirmation } from '@/lib/mothership/persistence/tool-confirm'
+import {
+  getToolConfirmation,
+  publishToolConfirmation,
+} from '@/lib/mothership/persistence/tool-confirm'
 import { waitForWorkflowToolCompletion } from '@/lib/mothership/request/tools/client'
 import { raceWorkflowToolClientPickup } from '@/lib/mothership/request/tools/workflow-client-fallback'
 import {
@@ -207,10 +210,13 @@ describe.runIf(Boolean(redisUrl))('settled client-claimed workflow tools', () =>
   }
 
   /**
-   * A claimed call whose bound execution paused at a human approval: the execute route settled the
-   * claim and its own report left the call running, as it does for every paused execution.
+   * A claimed call whose bound execution paused (a paused run's log stays `pending`) and whose
+   * execute route settled the claim, before the route reports it.
    */
-  async function claimedAndPaused(snapshot: string = UNRESUMABLE_SNAPSHOT) {
+  async function claimedAndPausedUnreported(
+    pauseKind: 'human' | 'time',
+    snapshot: string = UNRESUMABLE_SNAPSHOT
+  ) {
     const { toolCallId, executionId } = await claimed()
     await executionLog(toolCallId, executionId, 'pending')
     await db.insert(pausedExecutions).values({
@@ -226,17 +232,26 @@ describe.runIf(Boolean(redisUrl))('settled client-claimed workflow tools', () =>
           registeredAt: new Date().toISOString(),
           resumeStatus: 'paused',
           snapshotReady: true,
-          pauseKind: 'human',
+          pauseKind,
         },
       },
       totalPauseCount: 1,
     })
     await settleClientWorkflowToolExecution(toolCallId, executionId)
-    await reportSettledClientWorkflowTool({ toolCallId, executionId, workflowId })
-    expect(await toolRow(toolCallId)).toMatchObject({ status: 'running', result: null })
     return { toolCallId, executionId }
   }
 
+  /**
+   * A claimed call whose bound execution paused until a scheduled time: the run resumes by
+   * itself, so the execute route's report leaves the call held for the resume to settle.
+   */
+  async function claimedAndPaused(snapshot: string = UNRESUMABLE_SNAPSHOT) {
+    const ids = await claimedAndPausedUnreported('time', snapshot)
+    await reportSettledClientWorkflowTool({ ...ids, workflowId })
+    expect(await toolRow(ids.toolCallId)).toMatchObject({ status: 'running', result: null })
+    return ids
+  }
+
   async function setLogStatus(executionId: string, status: 'completed' | 'failed' | 'cancelled') {
     await db
       .update(workflowExecutionLogs)
@@ -461,6 +476,142 @@ describe.runIf(Boolean(redisUrl))('settled client-claimed workflow tools', () =>
     expect(await toolRow(toolCallId)).toMatchObject({ status: 'failed', claimedBy: null })
   })
 
+  it('answers a run paused for a person with the link to its form, and keeps that answer when the run is later cancelled', async () => {
+    const { toolCallId, executionId } = await claimedAndPausedUnreported('human')
+    const waiting = waitForWorkflowToolCompletion({ toolCallId, workflowId, timeoutMs: WAIT_MS })
+
+    await reportSettledClientWorkflowTool({ toolCallId, executionId, workflowId })
+
+    const paused = {
+      success: true,
+      status: 'paused',
+      workflowId,
+      executionId,
+      resumeUrl: `http://localhost:3000/resume/${workflowId}/${executionId}`,
+    }
+    const completion = await waiting
+    expect(completion).toMatchObject({ status: 'success', data: paused })
+    expect(completion?.message).toContain(paused.resumeUrl)
+    const settled = await toolRow(toolCallId)
+    expect(settled).toMatchObject({ status: 'completed', claimedBy: null, result: paused })
+    expect(await publishedConfirmation(toolCallId)).toMatchObject({
+      status: 'success',
+      executionId,
+    })
+
+    // The run is cancelled before anyone submits: its own report finds the call already answered.
+    expect(await PauseResumeManager.beginPausedCancellation(executionId, workflowId)).toBe(true)
+    expect(await PauseResumeManager.completePausedCancellation(executionId, workflowId)).toBe(true)
+    expect(await toolRow(toolCallId)).toMatchObject({
+      status: 'completed',
+      completedAt: settled.completedAt,
+      result: paused,
+    })
+  })
+
+  it("answers a paused run the worker's lapsed wait finds when the route's report never landed", async () => {
+    const { toolCallId, executionId } = await claimedAndPausedUnreported('human')
+    const runOnServer = vi.fn()
+
+    const outcome = await raceWorkflowToolClientPickup({
+      toolCallId,
+      workflowId,
+      timeoutMs: WAIT_MS,
+      graceMs: WAIT_MS,
+      waitTimeoutMs: 500,
+      runOnServer,
+    })
+
+    expect(outcome).toMatchObject({
+      winner: 'client',
+      completion: { status: 'success', data: { status: 'paused', workflowId, executionId } },
+    })
+    expect(runOnServer).not.toHaveBeenCalled()
+    expect(await toolRow(toolCallId)).toMatchObject({ status: 'completed', claimedBy: null })
+  })
+
+  it('answers a paused call still running when the person submitted before Chat read the pause', async () => {
+    const { toolCallId, executionId } = await claimedAndPausedUnreported('human')
+    await reportSettledClientWorkflowTool({ toolCallId, executionId, workflowId })
+    // The resume took the pause point and the resumed run is going.
+    const [pausedRow] = await db
+      .select({ id: pausedExecutions.id, pausePoints: pausedExecutions.pausePoints })
+      .from(pausedExecutions)
+      .where(eq(pausedExecutions.executionId, executionId))
+    await db
+      .update(pausedExecutions)
+      .set({
+        pausePoints: {
+          [APPROVAL_CONTEXT_ID]: {
+            ...(pausedRow.pausePoints as Record<string, Record<string, unknown>>)[
+              APPROVAL_CONTEXT_ID
+            ],
+            resumeStatus: 'resuming',
+          },
+        },
+      })
+      .where(eq(pausedExecutions.id, pausedRow.id))
+    await db
+      .update(workflowExecutionLogs)
+      .set({ status: 'running' })
+      .where(eq(workflowExecutionLogs.executionId, executionId))
+
+    const completion = await waitForWorkflowToolCompletion({
+      toolCallId,
+      workflowId,
+      timeoutMs: WAIT_MS,
+    })
+
+    expect(completion).toMatchObject({
+      status: 'background',
+      data: { status: 'running', workflowId, executionId },
+    })
+  })
+
+  it("never hands a call the link to another call's paused run", async () => {
+    const other = await claimedAndPausedUnreported('human')
+    const { toolCallId } = await claimed()
+    const waiting = waitForWorkflowToolCompletion({ toolCallId, workflowId, timeoutMs: WAIT_MS })
+    const claimedPause = { status: 'paused', workflowId, executionId: other.executionId }
+
+    await completeAsyncToolCall({ toolCallId, status: 'completed', result: claimedPause })
+    publishToolConfirmation({
+      toolCallId,
+      status: 'success',
+      timestamp: new Date().toISOString(),
+      data: claimedPause,
+      executionId: other.executionId,
+    })
+
+    const completion = await waiting
+    expect(completion?.data).not.toHaveProperty('resumeUrl')
+    expect(JSON.stringify(completion)).not.toContain('/resume/')
+  })
+
+  it('answers from the run log when a confirmation claims a pause the run is not in', async () => {
+    const { toolCallId, executionId } = await claimedAndSettled()
+    const waiting = waitForWorkflowToolCompletion({ toolCallId, workflowId, timeoutMs: WAIT_MS })
+    const claimedPause = {
+      status: 'paused',
+      workflowId,
+      executionId,
+      resumeUrl: 'https://elsewhere.test',
+    }
+
+    await completeAsyncToolCall({ toolCallId, status: 'completed', result: claimedPause })
+    publishToolConfirmation({
+      toolCallId,
+      status: 'success',
+      timestamp: new Date().toISOString(),
+      data: claimedPause,
+      executionId,
+    })
+
+    const completion = await waiting
+    expect(completion?.status).toBe('success')
+    expect(completion?.data).toEqual({ success: true, workflowId, executionId })
+  })
+
   it('moves a queued async run to the background when the browser never reports', async () => {
     const { toolCallId, executionId } = await claimed({ workflowId, async: true })
     const waiting = waitForWorkflowToolCompletion({ toolCallId, workflowId, timeoutMs: WAIT_MS })
diff --git a/apps/sim/lib/mothership/request/tools/workflow-client-settlement.ts b/apps/sim/lib/mothership/request/tools/workflow-client-settlement.ts
index c43c2b7847f..d6f493f61fd 100644
--- a/apps/sim/lib/mothership/request/tools/workflow-client-settlement.ts
+++ b/apps/sim/lib/mothership/request/tools/workflow-client-settlement.ts
@@ -1,5 +1,7 @@
 import {
   ASYNC_TOOL_CONFIRMATION_STATUS,
+  type AsyncConfirmationStatus,
+  type AsyncTerminalStatus,
   getTerminalConfirmationStatus,
   isTerminalAsyncStatus,
 } from '@/lib/mothership/async-runs/lifecycle'
@@ -9,10 +11,14 @@ import {
 } from '@/lib/mothership/async-runs/repository'
 import { publishToolConfirmation } from '@/lib/mothership/persistence/tool-confirm'
 import {
+  buildPausedWorkflowToolCompletion,
   createStructuralWorkflowToolCompletionData,
   getWorkflowToolCompletionMessage,
 } from '@/lib/mothership/tools/workflow-tools'
-import { getWorkflowExecutionLogStatus } from '@/lib/workflows/executor/execution-state'
+import {
+  getHumanPauseResumeUrl,
+  getWorkflowExecutionLogStatus,
+} from '@/lib/workflows/executor/execution-state'
 
 interface ReportClientWorkflowToolParams {
   toolCallId: string
@@ -20,6 +26,35 @@ interface ReportClientWorkflowToolParams {
   workflowId: string
 }
 
+/**
+ * Completes the call the execution claimed and publishes its answer. Only the first transition
+ * out of `running` lands; returns whether this one did.
+ */
+async function completeAndPublish(
+  { toolCallId, executionId }: ReportClientWorkflowToolParams,
+  rowStatus: AsyncTerminalStatus,
+  answer: { status: AsyncConfirmationStatus; message: string; data: Record<string, unknown> }
+): Promise<boolean> {
+  const completed = await completeClientWorkflowToolCall(
+    {
+      toolCallId,
+      status: rowStatus,
+      result: answer.data,
+      error: rowStatus === 'completed' ? null : answer.message,
+    },
+    executionId
+  )
+  if (!completed) return false
+
+  publishToolConfirmation({
+    toolCallId,
+    ...answer,
+    timestamp: new Date().toISOString(),
+    executionId,
+  })
+  return true
+}
+
 /**
  * Report a browser-claimed workflow tool's outcome from the execution it bound.
  *
@@ -32,39 +67,44 @@ interface ReportClientWorkflowToolParams {
  * started, which is what the browser reports from its stream error. Whichever of
  * this and the browser's report lands first is the one kept.
  */
-export async function reportSettledClientWorkflowTool({
-  toolCallId,
-  executionId,
-  workflowId,
-}: ReportClientWorkflowToolParams): Promise<void> {
+export async function reportSettledClientWorkflowTool(
+  params: ReportClientWorkflowToolParams
+): Promise<void> {
+  const { executionId, workflowId } = params
   const logStatus = await getWorkflowExecutionLogStatus(executionId, workflowId)
-  if (logStatus !== undefined && !isTerminalAsyncStatus(logStatus)) return
+  if (logStatus !== undefined && !isTerminalAsyncStatus(logStatus)) {
+    await reportPausedClientWorkflowTool(params)
+    return
+  }
 
   const executionStatus = logStatus ?? 'failed'
   const status = getTerminalConfirmationStatus(executionStatus)
-  const message = getWorkflowToolCompletionMessage(status)
-  const data = createStructuralWorkflowToolCompletionData(status, workflowId, executionId)
-  const completed = await completeClientWorkflowToolCall(
-    {
-      toolCallId,
-      status: executionStatus,
-      result: data,
-      error: executionStatus === 'completed' ? null : message,
-    },
-    executionId
-  )
-  if (!completed) return
-
-  publishToolConfirmation({
-    toolCallId,
+  await completeAndPublish(params, executionStatus, {
     status,
-    message,
-    timestamp: new Date().toISOString(),
-    data,
-    executionId,
+    message: getWorkflowToolCompletionMessage(status),
+    data: createStructuralWorkflowToolCompletionData(status, workflowId, executionId),
   })
 }
 
+/**
+ * Settle a browser-claimed workflow tool whose run is waiting on a person with the link to
+ * answer, so Chat tells the user instead of waiting on an answer nobody knows is owed. A run
+ * paused only on time resumes itself and keeps the call held. The call's claim on this
+ * execution is what binds them, so no other call can be answered here. Returns whether it settled.
+ */
+export async function reportPausedClientWorkflowTool(
+  params: ReportClientWorkflowToolParams
+): Promise<boolean> {
+  const { executionId, workflowId } = params
+  const resumeUrl = await getHumanPauseResumeUrl(executionId, workflowId)
+  if (!resumeUrl) return false
+  return completeAndPublish(
+    params,
+    'completed',
+    buildPausedWorkflowToolCompletion(workflowId, executionId, resumeUrl)
+  )
+}
+
 /**
  * Move a browser-claimed async run to the background once the execute route has
  * queued it, the same transition the browser reports after the queue accepts
diff --git a/apps/sim/lib/mothership/tools/workflow-tools.ts b/apps/sim/lib/mothership/tools/workflow-tools.ts
index 12dcebbddc5..9b4ebd2c059 100644
--- a/apps/sim/lib/mothership/tools/workflow-tools.ts
+++ b/apps/sim/lib/mothership/tools/workflow-tools.ts
@@ -171,6 +171,33 @@ export function getWorkflowToolCompletionMessage(status: AsyncConfirmationStatus
   return 'Workflow execution failed.'
 }
 
+/** Marks a workflow tool result whose run is waiting at a human pause, not finished. */
+export const WORKFLOW_TOOL_PAUSED_STATUS = 'paused'
+
+/**
+ * The answer for a workflow tool whose run paused for a person: where to answer, not an outcome.
+ * The model reads only `data` from a successful call, so the instruction travels there too.
+ */
+export function buildPausedWorkflowToolCompletion(
+  workflowId: string,
+  executionId: string,
+  resumeUrl: string
+) {
+  const message = `The workflow paused at a Human in the Loop block and is waiting for a person to respond; it has not finished. Give the user this link to review and submit the form: ${resumeUrl}. The run continues by itself once they submit, so do not resume it for them. Read the run afterwards for its result.`
+  return {
+    status: ASYNC_TOOL_CONFIRMATION_STATUS.success,
+    message,
+    data: {
+      success: true,
+      status: WORKFLOW_TOOL_PAUSED_STATUS,
+      workflowId,
+      executionId,
+      resumeUrl,
+      message,
+    },
+  }
+}
+
 export function createStructuralWorkflowToolCompletionData(
   status: AsyncConfirmationStatus,
   workflowId?: string,
diff --git a/apps/sim/lib/workflows/executor/execution-state.ts b/apps/sim/lib/workflows/executor/execution-state.ts
index f9391cf6717..aff65c87840 100644
--- a/apps/sim/lib/workflows/executor/execution-state.ts
+++ b/apps/sim/lib/workflows/executor/execution-state.ts
@@ -1,9 +1,12 @@
 import { db } from '@sim/db'
-import { workflowExecutionLogs } from '@sim/db/schema'
+import { pausedExecutions, workflowExecutionLogs } from '@sim/db/schema'
 import { filterUndefined, isRecordLike } from '@sim/utils/object'
 import { and, desc, eq, or, sql } from 'drizzle-orm'
+import { getBaseUrl } from '@/lib/core/utils/urls'
 import { materializeExecutionData, TRACE_STORE_REF_KEY } from '@/lib/logs/execution/trace-store'
+import { buildResumeUiUrl } from '@/executor/constants'
 import type { SerializableExecutionState } from '@/executor/execution/types'
+import type { PausePoint } from '@/executor/types'
 import {
   isResolvedSecretTraceProvenanceV1,
   type ResolvedSecretTraceProvenanceV1,
@@ -188,6 +191,41 @@ export async function getWorkflowExecutionCopilotToolCallId(
   return typeof toolCallId === 'string' ? toolCallId : undefined
 }
 
+/** A paused execution's pause points, stored keyed by context id (older rows: an array). */
+export function normalizePausePoints(raw: unknown): PausePoint[] {
+  if (!raw) return []
+  if (Array.isArray(raw)) return raw as PausePoint[]
+  if (typeof raw === 'object') return Object.values(raw as Record<string, PausePoint>)
+  return []
+}
+
+/**
+ * The page where a person answers the execution's open pauses, or null when nothing waits on a
+ * person: the run is not paused, or is paused only on time and resumes itself.
+ */
+export async function getHumanPauseResumeUrl(
+  executionId: string,
+  workflowId: string
+): Promise<string | null> {
+  const [paused] = await db
+    .select({ status: pausedExecutions.status, pausePoints: pausedExecutions.pausePoints })
+    .from(pausedExecutions)
+    .where(
+      and(
+        eq(pausedExecutions.executionId, executionId),
+        eq(pausedExecutions.workflowId, workflowId)
+      )
+    )
+    .limit(1)
+  if (!paused || (paused.status !== 'paused' && paused.status !== 'partially_resumed')) {
+    return null
+  }
+  const waitsOnPerson = normalizePausePoints(paused.pausePoints).some(
+    (point) => point.resumeStatus === 'paused' && point.pauseKind !== 'time'
+  )
+  return waitsOnPerson ? buildResumeUiUrl(getBaseUrl(), workflowId, executionId) : null
+}
+
 /**
  * The message an error finalization (`force_failed`) stored as the run's `finalOutput.error`.
  * Any other run's `finalOutput.error` is the workflow's own data, not a failure message.
diff --git a/apps/sim/lib/workflows/executor/execution-status.ts b/apps/sim/lib/workflows/executor/execution-status.ts
index 8137808fcdf..ec854781039 100644
--- a/apps/sim/lib/workflows/executor/execution-status.ts
+++ b/apps/sim/lib/workflows/executor/execution-status.ts
@@ -14,6 +14,7 @@ import {
   RESUME_EXECUTION_JOB_ID_PREFIX,
   WORKFLOW_EXECUTION_JOB_ID_PREFIX,
 } from '@/lib/workflows/executor/execution-job-ids'
+import { normalizePausePoints } from '@/lib/workflows/executor/execution-state'
 import { getAutomaticResumeWaitingMetadata } from '@/lib/workflows/executor/paused-execution-metadata'
 import type { PausePoint } from '@/executor/types'
 
@@ -69,13 +70,6 @@ function pickEarliestPausePoint(points: PausePoint[]): PausePoint | null {
   }, null)
 }
 
-function normalizePausePoints(raw: unknown): PausePoint[] {
-  if (!raw) return []
-  if (Array.isArray(raw)) return raw as PausePoint[]
-  if (typeof raw === 'object') return Object.values(raw as Record<string, PausePoint>)
-  return []
-}
-
 function extractError(executionData: unknown): string | null {
   if (!executionData || typeof executionData !== 'object') return null
   const data = executionData as ExecutionDataShape

From 2441e8d115525eb2d42ea856e49d043b76dd900d Mon Sep 17 00:00:00 2001
From: Waleed <walif6@gmail.com>
Date: Fri, 6 Nov 2026 12:20:14 -0800
Subject: [PATCH 3/3] fix(billing): settle hosted fal generations to their
 exact cost (#9750)

* fix(billing): settle hosted fal generations to their exact cost

* fix(billing): settle into the payer's current period and cancel on trusted fal URLs

* fix(billing): settle zero fal estimates and fix the settlement fixture payer
---
 apps/sim/background/falai-cost-settlement.ts  |  37 +++
 .../sim/lib/internal/image/operations.test.ts |  14 +-
 apps/sim/lib/internal/image/operations.ts     | 232 ++++++++++--------
 apps/sim/lib/internal/video/client.ts         | 163 ++++++------
 apps/sim/lib/media/falai-audio.ts             |   4 +-
 apps/sim/lib/media/falai-video.ts             |   2 +-
 apps/sim/lib/media/falai.test.ts              |  19 +-
 apps/sim/lib/media/falai.ts                   |  18 +-
 .../tools/server/media/generate-audio.ts      |  15 +-
 .../tools/server/media/generate-video.ts      |  15 +-
 .../server/media/model-boundaries.test.ts     |   8 +-
 .../write-target-precheck.integration.ts      |   8 +-
 apps/sim/lib/tools/falai-pricing.ts           |  10 +
 .../lib/tools/falai-settlement.integration.ts | 175 +++++++++++++
 apps/sim/lib/tools/falai-settlement.ts        | 176 +++++++++++++
 apps/sim/tools/image/generate.ts              |   1 +
 apps/sim/tools/index.test.ts                  |  74 ++++++
 apps/sim/tools/index.ts                       |  54 +++-
 apps/sim/tools/types.ts                       |   5 +
 apps/sim/tools/video/falai.ts                 |   1 +
 20 files changed, 822 insertions(+), 209 deletions(-)
 create mode 100644 apps/sim/background/falai-cost-settlement.ts
 create mode 100644 apps/sim/lib/tools/falai-settlement.integration.ts
 create mode 100644 apps/sim/lib/tools/falai-settlement.ts

diff --git a/apps/sim/background/falai-cost-settlement.ts b/apps/sim/background/falai-cost-settlement.ts
new file mode 100644
index 00000000000..7543765b79e
--- /dev/null
+++ b/apps/sim/background/falai-cost-settlement.ts
@@ -0,0 +1,37 @@
+import { createLogger } from '@sim/logger'
+import { task } from '@trigger.dev/sdk'
+import {
+  FALAI_COST_SETTLEMENT_TASK_ID,
+  type FalAICostSettlementPayload,
+  settleFalAICost,
+} from '@/lib/tools/falai-settlement'
+
+const logger = createLogger('FalAICostSettlementTask')
+
+/**
+ * Settles a hosted fal generation billed on an estimate to fal's exact charge. A receipt fal
+ * has not recorded yet fails the attempt so the retries keep looking for about an hour; past
+ * that the estimate stands.
+ */
+export const falaiCostSettlementTask = task({
+  id: FALAI_COST_SETTLEMENT_TASK_ID,
+  retry: {
+    maxAttempts: 8,
+    factor: 2,
+    minTimeoutInMs: 60_000,
+    maxTimeoutInMs: 15 * 60_000,
+  },
+  queue: { concurrencyLimit: 5 },
+  run: async (payload: FalAICostSettlementPayload) => {
+    const outcome = await settleFalAICost(payload)
+    if (outcome === 'pending') {
+      throw new Error(`fal has not recorded the charge for request ${payload.requestId} yet`)
+    }
+    logger.info('fal cost settlement finished', {
+      requestId: payload.requestId,
+      endpointId: payload.endpointId,
+      outcome,
+    })
+    return { outcome }
+  },
+})
diff --git a/apps/sim/lib/internal/image/operations.test.ts b/apps/sim/lib/internal/image/operations.test.ts
index 7021860ffb1..1a3a3d92d37 100644
--- a/apps/sim/lib/internal/image/operations.test.ts
+++ b/apps/sim/lib/internal/image/operations.test.ts
@@ -102,7 +102,7 @@ describe('image operations', () => {
     ])
   })
 
-  it('cancels polling without resubmitting or storing an image', async () => {
+  it('cancels the fal request when polling stops, without resubmitting or storing an image', async () => {
     const controller = new AbortController()
     mocks.fetch.mockResolvedValueOnce(
       Response.json({
@@ -121,12 +121,16 @@ describe('image operations', () => {
       })
     ).rejects.toMatchObject({ name: 'AbortError' })
 
-    expect(mocks.fetch).toHaveBeenCalledTimes(1)
+    expect(mocks.fetch).toHaveBeenCalledTimes(2)
+    expect(mocks.fetch).toHaveBeenLastCalledWith(
+      expect.stringMatching(/^https:\/\/queue\.fal\.run\/.+\/requests\/job-2\/cancel$/),
+      expect.objectContaining({ method: 'PUT' })
+    )
     expect(mockSecureFetchWithPinnedIP).not.toHaveBeenCalled()
     expect(mockUploadCopilotFile).not.toHaveBeenCalled()
   })
 
-  it('rejects foreign fal queue hosts before sending credentials', async () => {
+  it('rejects foreign fal queue hosts before sending credentials and cancels on the fal queue', async () => {
     mocks.fetch.mockResolvedValueOnce(
       Response.json({
         request_id: 'foreign-job',
@@ -143,6 +147,10 @@ describe('image operations', () => {
     expect(response.status).toBe(500)
     expect(await response.json()).toMatchObject({ error: 'Invalid Fal.ai queue URL' })
     expect(mockSecureFetchWithPinnedIP).not.toHaveBeenCalled()
+    expect(mocks.fetch).toHaveBeenLastCalledWith(
+      expect.stringMatching(/^https:\/\/queue\.fal\.run\/.+\/requests\/foreign-job\/cancel$/),
+      expect.objectContaining({ method: 'PUT' })
+    )
   })
 
   it('retrieves nested fal jobs from the documented application request path', async () => {
diff --git a/apps/sim/lib/internal/image/operations.ts b/apps/sim/lib/internal/image/operations.ts
index bc505761e00..de2202cba7f 100644
--- a/apps/sim/lib/internal/image/operations.ts
+++ b/apps/sim/lib/internal/image/operations.ts
@@ -19,6 +19,7 @@ import {
 import { MAX_REMOTE_IMAGE_BYTES } from '@/lib/internal/image/fetch'
 import { buildImageGenerationRequest } from '@/lib/internal/image/request'
 import type { ImageGenerationInput, ImageProvider } from '@/lib/internal/image/schema'
+import { cancelFalRequest } from '@/lib/media/falai'
 import { FalAIResultError, fetchFalAIResult } from '@/lib/media/falai-result'
 import { recordServiceMeteringFailure } from '@/lib/mothership/billing/service-observer'
 import type { FalAICostMetadata } from '@/lib/tools/falai-pricing'
@@ -456,134 +457,149 @@ async function generateWithFalAI(
     throw new Error('Fal.ai queue response missing request_id')
   }
 
-  const statusUrl = falQueueUrl(
-    getStringProperty(createData, 'status_url') ||
-      buildFalAIQueueUrl(endpoint, falRequestId, 'status')
-  )
-  const responseUrl = falQueueUrl(
-    getStringProperty(createData, 'response_url') ||
-      buildFalAIQueueUrl(endpoint, falRequestId, 'response')
-  )
+  /** Built from the endpoint, never a provider URL, so a rejected one can still be cancelled. */
+  const cancelUrl = `${buildFalAIQueueUrl(endpoint, falRequestId, 'response')}/cancel`
 
   logger.info('Fal.ai image request created', { requestId, falRequestId })
 
-  const statusValidation = await validateUrlWithDNS(statusUrl, 'statusUrl', 'contentFetch')
-  if (!statusValidation.isValid) {
-    throw new Error(statusValidation.error)
-  }
-
-  const pollIntervalMs = 3000
-  const maxAttempts = Math.ceil(getMaxExecutionTimeout() / pollIntervalMs)
-  let attempts = 0
-
-  while (attempts < maxAttempts) {
-    await interruptibleSleep(pollIntervalMs, signal)
-    signal?.throwIfAborted()
-
-    const statusResponse = await secureFetchWithPinnedIP(statusUrl, statusValidation.resolvedIP, {
-      profile: 'contentFetch',
-      maxRedirects: 0,
-      headers: {
-        Authorization: `Key ${apiKey}`,
-      },
-      maxResponseBytes: MAX_IMAGE_JSON_BYTES,
-      signal,
-    })
+  let reachedTerminalStatus = false
+  try {
+    const statusUrl = falQueueUrl(
+      getStringProperty(createData, 'status_url') ||
+        buildFalAIQueueUrl(endpoint, falRequestId, 'status')
+    )
+    const responseUrl = falQueueUrl(
+      getStringProperty(createData, 'response_url') ||
+        buildFalAIQueueUrl(endpoint, falRequestId, 'response')
+    )
 
-    if (!statusResponse.ok) {
-      await readResponseTextWithLimit(statusResponse, {
-        maxBytes: DEFAULT_MAX_ERROR_BODY_BYTES,
-        label: 'Fal.ai status error response',
-        signal,
-      }).catch(() => '')
-      throw new Error(`Fal.ai status check failed: ${statusResponse.status}`)
+    const statusValidation = await validateUrlWithDNS(statusUrl, 'statusUrl', 'contentFetch')
+    if (!statusValidation.isValid) {
+      throw new Error(statusValidation.error)
     }
 
-    const statusData = await readResponseJsonWithLimit(statusResponse, {
-      maxBytes: MAX_IMAGE_JSON_BYTES,
-      label: 'Fal.ai status response',
-      signal,
-    })
-    if (!isRecordLike(statusData)) {
-      throw new Error('Invalid Fal.ai status response')
-    }
+    const pollIntervalMs = 3000
+    const maxAttempts = Math.ceil(getMaxExecutionTimeout() / pollIntervalMs)
+    let attempts = 0
 
-    const status = getStringProperty(statusData, 'status')
-    if (status === 'COMPLETED') {
-      const { data: resultData, cost: falaiCost } = await fetchFalAIResult({
-        apiKey,
-        endpointId: endpoint,
-        requestId: falRequestId,
-        queueError: statusData.error,
+    while (attempts < maxAttempts) {
+      await interruptibleSleep(pollIntervalMs, signal)
+      signal?.throwIfAborted()
+
+      const statusResponse = await secureFetchWithPinnedIP(statusUrl, statusValidation.resolvedIP, {
+        profile: 'contentFetch',
+        maxRedirects: 0,
+        headers: {
+          Authorization: `Key ${apiKey}`,
+        },
         maxResponseBytes: MAX_IMAGE_JSON_BYTES,
-        trackCost: body.useHostedCostTracking,
-        onCost: onFalCost,
         signal,
-        fetchResponse: async (resultSignal) => {
-          const resultUrl = falQueueUrl(
-            getStringProperty(statusData, 'response_url') || responseUrl
-          )
-          const resultValidation = await validateUrlWithDNS(resultUrl, 'resultUrl', 'contentFetch')
-          if (!resultValidation.isValid) throw new Error(resultValidation.error)
-          return secureFetchWithPinnedIP(resultUrl, resultValidation.resolvedIP, {
-            profile: 'contentFetch',
-            maxRedirects: 0,
-            headers: { Authorization: `Key ${apiKey}` },
-            maxResponseBytes: MAX_IMAGE_JSON_BYTES,
-            signal: resultSignal,
-          })
-        },
       })
 
-      if (!isRecordLike(resultData)) {
-        throw new Error('Invalid Fal.ai result response')
+      if (!statusResponse.ok) {
+        await readResponseTextWithLimit(statusResponse, {
+          maxBytes: DEFAULT_MAX_ERROR_BODY_BYTES,
+          label: 'Fal.ai status error response',
+          signal,
+        }).catch(() => '')
+        throw new Error(`Fal.ai status check failed: ${statusResponse.status}`)
       }
 
-      const firstImage =
-        prepared.model.output === 'image' && isRecordLike(resultData.image)
-          ? resultData.image
-          : firstRecord(resultData.images)
-      const imageUrl =
-        getStringProperty(firstImage, 'url') ||
-        getStringProperty(firstImage, 'data') ||
-        getStringProperty(firstImage, 'content')
-      if (!imageUrl) {
-        throw new Error('No image URL in Fal.ai response')
+      const statusData = await readResponseJsonWithLimit(statusResponse, {
+        maxBytes: MAX_IMAGE_JSON_BYTES,
+        label: 'Fal.ai status response',
+        signal,
+      })
+      if (!isRecordLike(statusData)) {
+        throw new Error('Invalid Fal.ai status response')
       }
 
-      const downloaded = await bufferFromImageUrl(imageUrl, signal)
-      const contentType =
-        getStringProperty(firstImage, 'content_type') ||
-        getStringProperty(firstImage, 'contentType') ||
-        downloaded.contentType
-      const fileName =
-        getStringProperty(firstImage, 'file_name') ||
-        getStringProperty(firstImage, 'fileName') ||
-        `falai-${model}.${extensionFromContentType(contentType)}`
-
-      return {
-        buffer: downloaded.buffer,
-        contentType,
-        fileName,
-        provider: 'falai',
-        model,
-        sourceUrl: imageUrl.startsWith('data:') ? undefined : imageUrl,
-        description: getStringProperty(resultData, 'description'),
-        revisedPrompt: getStringProperty(resultData, 'revised_prompt'),
-        seed: getNumberProperty(resultData, 'seed'),
-        jobId: falRequestId,
-        falaiCost,
+      const status = getStringProperty(statusData, 'status')
+      if (status === 'COMPLETED') {
+        reachedTerminalStatus = true
+        const { data: resultData, cost: falaiCost } = await fetchFalAIResult({
+          apiKey,
+          endpointId: endpoint,
+          requestId: falRequestId,
+          queueError: statusData.error,
+          maxResponseBytes: MAX_IMAGE_JSON_BYTES,
+          trackCost: body.useHostedCostTracking,
+          onCost: onFalCost,
+          signal,
+          fetchResponse: async (resultSignal) => {
+            const resultUrl = falQueueUrl(
+              getStringProperty(statusData, 'response_url') || responseUrl
+            )
+            const resultValidation = await validateUrlWithDNS(
+              resultUrl,
+              'resultUrl',
+              'contentFetch'
+            )
+            if (!resultValidation.isValid) throw new Error(resultValidation.error)
+            return secureFetchWithPinnedIP(resultUrl, resultValidation.resolvedIP, {
+              profile: 'contentFetch',
+              maxRedirects: 0,
+              headers: { Authorization: `Key ${apiKey}` },
+              maxResponseBytes: MAX_IMAGE_JSON_BYTES,
+              signal: resultSignal,
+            })
+          },
+        })
+
+        if (!isRecordLike(resultData)) {
+          throw new Error('Invalid Fal.ai result response')
+        }
+
+        const firstImage =
+          prepared.model.output === 'image' && isRecordLike(resultData.image)
+            ? resultData.image
+            : firstRecord(resultData.images)
+        const imageUrl =
+          getStringProperty(firstImage, 'url') ||
+          getStringProperty(firstImage, 'data') ||
+          getStringProperty(firstImage, 'content')
+        if (!imageUrl) {
+          throw new Error('No image URL in Fal.ai response')
+        }
+
+        const downloaded = await bufferFromImageUrl(imageUrl, signal)
+        const contentType =
+          getStringProperty(firstImage, 'content_type') ||
+          getStringProperty(firstImage, 'contentType') ||
+          downloaded.contentType
+        const fileName =
+          getStringProperty(firstImage, 'file_name') ||
+          getStringProperty(firstImage, 'fileName') ||
+          `falai-${model}.${extensionFromContentType(contentType)}`
+
+        return {
+          buffer: downloaded.buffer,
+          contentType,
+          fileName,
+          provider: 'falai',
+          model,
+          sourceUrl: imageUrl.startsWith('data:') ? undefined : imageUrl,
+          description: getStringProperty(resultData, 'description'),
+          revisedPrompt: getStringProperty(resultData, 'revised_prompt'),
+          seed: getNumberProperty(resultData, 'seed'),
+          jobId: falRequestId,
+          falaiCost,
+        }
       }
-    }
 
-    if (['ERROR', 'FAILED', 'CANCELLED'].includes(status || '')) {
-      throw new Error(`Fal.ai generation failed: ${getFalAIErrorMessage(statusData.error)}`)
+      if (['ERROR', 'FAILED', 'CANCELLED'].includes(status || '')) {
+        reachedTerminalStatus = true
+        throw new Error(`Fal.ai generation failed: ${getFalAIErrorMessage(statusData.error)}`)
+      }
+
+      attempts += 1
     }
 
-    attempts += 1
+    throw new Error('Fal.ai image generation timed out')
+  } catch (error) {
+    if (!reachedTerminalStatus) await cancelFalRequest(cancelUrl, apiKey, falRequestId)
+    throw error
   }
-
-  throw new Error('Fal.ai image generation timed out')
 }
 
 async function storeGeneratedImage(
diff --git a/apps/sim/lib/internal/video/client.ts b/apps/sim/lib/internal/video/client.ts
index 6ef27ce4565..9f8a8137352 100644
--- a/apps/sim/lib/internal/video/client.ts
+++ b/apps/sim/lib/internal/video/client.ts
@@ -17,7 +17,7 @@ import {
 import { buildDirectVideoRequest } from '@/lib/internal/video/direct-request'
 import { buildFalVideoRequest, getFalAIValidationError } from '@/lib/internal/video/fal-request'
 import { getFalVideoModel } from '@/lib/media/fal-video-catalog'
-import { downloadFalMedia } from '@/lib/media/falai'
+import { cancelFalRequest, downloadFalMedia } from '@/lib/media/falai'
 import { fetchFalAIResult } from '@/lib/media/falai-result'
 import type { FalAICostMetadata } from '@/lib/tools/falai-pricing'
 import { downloadFileFromStorage } from '@/lib/uploads/utils/file.server'
@@ -393,100 +393,113 @@ async function generateWithFalAI(
 
   const app = endpoint.split('/', 2).join('/')
   const requestUrl = `https://queue.fal.run/${app}/requests/${encodeURIComponent(requestIdFal)}`
-  const statusUrl = falQueueUrl(
-    getStringProperty(createData, 'status_url') || `${requestUrl}/status`
-  )
-  const responseUrl = falQueueUrl(getStringProperty(createData, 'response_url') || requestUrl)
+  /** Built from the endpoint, never a provider URL, so a rejected one can still be cancelled. */
+  const cancelUrl = `${requestUrl}/cancel`
 
   logger.info(`Fal.ai request created: ${requestIdFal}`, { requestId })
 
-  const maxAttempts = Math.ceil(getMaxExecutionTimeout() / POLL_INTERVAL_MS)
-  let attempts = 0
-
-  while (attempts < maxAttempts) {
-    await waitForProvider(context)
-
-    const statusResponse = await fetch(statusUrl, {
-      redirect: 'error',
-      headers: {
-        Authorization: `Key ${apiKey}`,
-      },
-      signal,
-    })
+  let reachedTerminalStatus = false
+  try {
+    const statusUrl = falQueueUrl(
+      getStringProperty(createData, 'status_url') || `${requestUrl}/status`
+    )
+    const responseUrl = falQueueUrl(getStringProperty(createData, 'response_url') || requestUrl)
 
-    if (!statusResponse.ok) {
-      await readVideoErrorText(statusResponse, 'Fal.ai status error response')
-      throw new Error(`Fal.ai status check failed: ${statusResponse.status}`)
-    }
+    const maxAttempts = Math.ceil(getMaxExecutionTimeout() / POLL_INTERVAL_MS)
+    let attempts = 0
 
-    const statusData = await readVideoJson<unknown>(statusResponse, 'Fal.ai status response')
-    if (!isRecordLike(statusData)) {
-      throw new Error('Invalid Fal.ai status response')
-    }
+    while (attempts < maxAttempts) {
+      await waitForProvider(context)
 
-    if (getStringProperty(statusData, 'status') === 'COMPLETED') {
-      const { data: resultData, cost: falaiCost } = await fetchFalAIResult({
-        apiKey,
-        endpointId: endpoint,
-        requestId: requestIdFal,
-        queueError: statusData.error,
-        maxResponseBytes: MAX_VIDEO_JSON_BYTES,
-        trackCost: useHostedCostTracking,
-        onCost: context.onFalCost,
+      const statusResponse = await fetch(statusUrl, {
+        redirect: 'error',
+        headers: {
+          Authorization: `Key ${apiKey}`,
+        },
         signal,
-        fetchResponse: (resultSignal) =>
-          fetch(falQueueUrl(getStringProperty(statusData, 'response_url') || responseUrl), {
-            redirect: 'error',
-            headers: { Authorization: `Key ${apiKey}` },
-            signal: resultSignal,
-          }),
       })
 
-      if (!isRecordLike(resultData)) {
-        throw new Error('Invalid Fal.ai result response')
+      if (!statusResponse.ok) {
+        await readVideoErrorText(statusResponse, 'Fal.ai status error response')
+        throw new Error(`Fal.ai status check failed: ${statusResponse.status}`)
       }
 
-      const videoOutput = isRecordLike(resultData.video) ? resultData.video : undefined
-      const fallbackOutput = isRecordLike(resultData.output) ? resultData.output : undefined
-      const videoUrl =
-        getStringProperty(videoOutput, 'url') || getStringProperty(fallbackOutput, 'url')
-      if (!videoUrl) {
-        throw new Error('No video URL in response')
+      const statusData = await readVideoJson<unknown>(statusResponse, 'Fal.ai status response')
+      if (!isRecordLike(statusData)) {
+        throw new Error('Invalid Fal.ai status response')
       }
 
-      const { buffer } = await downloadFalMedia(videoUrl, signal)
-      const catalogModel = getFalVideoModel(model)
-      const legacyMetadata = !catalogModel || catalogModel.legacyId === model
-      let width = getNumberProperty(videoOutput, 'width')
-      let height = getNumberProperty(videoOutput, 'height')
-      if (legacyMetadata && !width && aspectRatio?.includes(':')) {
-        const dims = getVideoDimensions(aspectRatio, resolution || '1080p')
-        width = dims.width
-        height = dims.height
+      if (getStringProperty(statusData, 'status') === 'COMPLETED') {
+        reachedTerminalStatus = true
+        const { data: resultData, cost: falaiCost } = await fetchFalAIResult({
+          apiKey,
+          endpointId: endpoint,
+          requestId: requestIdFal,
+          queueError: statusData.error,
+          maxResponseBytes: MAX_VIDEO_JSON_BYTES,
+          trackCost: useHostedCostTracking,
+          onCost: context.onFalCost,
+          signal,
+          fetchResponse: (resultSignal) =>
+            fetch(falQueueUrl(getStringProperty(statusData, 'response_url') || responseUrl), {
+              redirect: 'error',
+              headers: { Authorization: `Key ${apiKey}` },
+              signal: resultSignal,
+            }),
+        })
+
+        if (!isRecordLike(resultData)) {
+          throw new Error('Invalid Fal.ai result response')
+        }
+
+        const videoOutput = isRecordLike(resultData.video) ? resultData.video : undefined
+        const fallbackOutput = isRecordLike(resultData.output) ? resultData.output : undefined
+        const videoUrl =
+          getStringProperty(videoOutput, 'url') || getStringProperty(fallbackOutput, 'url')
+        if (!videoUrl) {
+          throw new Error('No video URL in response')
+        }
+
+        const { buffer } = await downloadFalMedia(videoUrl, signal)
+        const catalogModel = getFalVideoModel(model)
+        const legacyMetadata = !catalogModel || catalogModel.legacyId === model
+        let width = getNumberProperty(videoOutput, 'width')
+        let height = getNumberProperty(videoOutput, 'height')
+        if (legacyMetadata && !width && aspectRatio?.includes(':')) {
+          const dims = getVideoDimensions(aspectRatio, resolution || '1080p')
+          width = dims.width
+          height = dims.height
+        }
+
+        return {
+          buffer,
+          width: width ?? (legacyMetadata ? 1920 : undefined),
+          height: height ?? (legacyMetadata ? 1080 : undefined),
+          jobId: requestIdFal,
+          duration:
+            getNumberProperty(videoOutput, 'duration') ??
+            getNumberProperty(resultData, 'duration') ??
+            duration ??
+            (legacyMetadata ? 5 : undefined),
+          falaiCost,
+        }
       }
 
-      return {
-        buffer,
-        width: width ?? (legacyMetadata ? 1920 : undefined),
-        height: height ?? (legacyMetadata ? 1080 : undefined),
-        jobId: requestIdFal,
-        duration:
-          getNumberProperty(videoOutput, 'duration') ??
-          getNumberProperty(resultData, 'duration') ??
-          duration ??
-          (legacyMetadata ? 5 : undefined),
-        falaiCost,
+      if (
+        ['ERROR', 'FAILED', 'CANCELLED'].includes(getStringProperty(statusData, 'status') || '')
+      ) {
+        reachedTerminalStatus = true
+        throw new Error(`Fal.ai generation failed: ${getFalAIErrorMessage(statusData.error)}`)
       }
-    }
 
-    if (['ERROR', 'FAILED', 'CANCELLED'].includes(getStringProperty(statusData, 'status') || '')) {
-      throw new Error(`Fal.ai generation failed: ${getFalAIErrorMessage(statusData.error)}`)
+      attempts++
     }
 
-    attempts++
+    throw new Error('Fal.ai generation timed out')
+  } catch (error) {
+    if (!reachedTerminalStatus) await cancelFalRequest(cancelUrl, apiKey, requestIdFal)
+    throw error
   }
-
-  throw new Error('Fal.ai generation timed out')
 }
 
 function getVideoDimensions(
diff --git a/apps/sim/lib/media/falai-audio.ts b/apps/sim/lib/media/falai-audio.ts
index e9705d9e89e..719eb68187e 100644
--- a/apps/sim/lib/media/falai-audio.ts
+++ b/apps/sim/lib/media/falai-audio.ts
@@ -159,7 +159,7 @@ export async function generateFalAudio(params: GenerateFalAudioParams): Promise<
       { tool: 'generate_audio', envVarName },
       params.signal
     )
-    const cost = await recordFalCost(apiKey, model, requestId, params.onCost)
+    const cost = await recordFalCost({ apiKey, envVarName }, model, requestId, params.onCost)
     const url = extractFalMediaUrl(data, ['audio', 'audio_url', 'audio_file', 'output'])
     if (!url) throw new Error('No audio URL in Fal.ai clone response')
     const { buffer, contentType } = await downloadFalMedia(url, params.signal)
@@ -185,7 +185,7 @@ export async function generateFalAudio(params: GenerateFalAudioParams): Promise<
     { tool: 'generate_audio', envVarName },
     params.signal
   )
-  const cost = await recordFalCost(apiKey, model, requestId, params.onCost)
+  const cost = await recordFalCost({ apiKey, envVarName }, model, requestId, params.onCost)
   const url = extractFalMediaUrl(data, ['audio', 'audio_url', 'audio_file', 'output'])
   if (!url) throw new Error('No audio URL in Fal.ai response')
 
diff --git a/apps/sim/lib/media/falai-video.ts b/apps/sim/lib/media/falai-video.ts
index ddeb7e56b6d..b1eb49f1923 100644
--- a/apps/sim/lib/media/falai-video.ts
+++ b/apps/sim/lib/media/falai-video.ts
@@ -184,7 +184,7 @@ export async function generateFalVideo(params: GenerateFalVideoParams): Promise<
     { tool: 'generate_video', envVarName },
     params.signal
   )
-  const cost = await recordFalCost(apiKey, endpoint, requestId, params.onCost)
+  const cost = await recordFalCost({ apiKey, envVarName }, endpoint, requestId, params.onCost)
   const url = extractFalMediaUrl(data, ['video', 'output'])
   if (!url) throw new Error('No video URL in Fal.ai response')
 
diff --git a/apps/sim/lib/media/falai.test.ts b/apps/sim/lib/media/falai.test.ts
index 410ec48b575..0bde5560f7c 100644
--- a/apps/sim/lib/media/falai.test.ts
+++ b/apps/sim/lib/media/falai.test.ts
@@ -14,6 +14,7 @@ import { generateFalAudio } from '@/lib/media/falai-audio'
 import { generateFalVideo } from '@/lib/media/falai-video'
 
 const FAL_KEY_USE = { tool: 'generate_video', envVarName: 'FALAI_API_KEY' } as const
+const HOSTED_KEY = { envVarName: FAL_KEY_USE.envVarName }
 const CANCEL_URL = 'https://queue.fal.run/fal-ai/model/requests/req-1/cancel'
 const STATUS_URL = 'https://queue.fal.run/fal-ai/model/requests/req-1/status'
 
@@ -337,7 +338,8 @@ describe('billing a fal generation', () => {
       expect(await generation).toEqual(new Error('watchdog'))
       expect(onCost).toHaveBeenCalledTimes(1)
       expect(onCost).toHaveBeenCalledWith(
-        expect.objectContaining({ source: 'billing_events', costDollars: 0.04 })
+        expect.objectContaining({ source: 'billing_events', costDollars: 0.04 }),
+        HOSTED_KEY
       )
     }
   )
@@ -353,7 +355,10 @@ describe('billing a fal generation', () => {
 
       expect(await generation).toMatch(/No (audio|video) URL/)
       expect(onCost).toHaveBeenCalledTimes(1)
-      expect(onCost).toHaveBeenCalledWith(expect.objectContaining({ source: 'billing_events' }))
+      expect(onCost).toHaveBeenCalledWith(
+        expect.objectContaining({ source: 'billing_events' }),
+        HOSTED_KEY
+      )
     }
   )
 
@@ -373,7 +378,8 @@ describe('billing a fal generation', () => {
     expect(await generation).toEqual(new Error('watchdog'))
     expect(onCost).toHaveBeenCalledTimes(1)
     expect(onCost).toHaveBeenCalledWith(
-      expect.objectContaining({ source: 'billing_events', costDollars: 0.04 })
+      expect.objectContaining({ source: 'billing_events', costDollars: 0.04 }),
+      HOSTED_KEY
     )
     expect(inputValidationMockFns.mockSecureFetchWithPinnedIP).not.toHaveBeenCalled()
   })
@@ -393,7 +399,10 @@ describe('billing a fal generation', () => {
 
     expect(await generation).toEqual(new Error('watchdog'))
     expect(onCost).toHaveBeenCalledTimes(1)
-    expect(onCost).toHaveBeenCalledWith(expect.objectContaining({ source: 'fallback_floor' }))
+    expect(onCost).toHaveBeenCalledWith(
+      expect.objectContaining({ source: 'fallback_floor' }),
+      HOSTED_KEY
+    )
   })
 
   it('bills a generation that completes and downloads exactly once', async () => {
@@ -407,7 +416,7 @@ describe('billing a fal generation', () => {
 
     expect(audio.buffer.toString()).toBe('audio')
     expect(onCost).toHaveBeenCalledTimes(1)
-    expect(onCost).toHaveBeenCalledWith(audio.cost)
+    expect(onCost).toHaveBeenCalledWith(audio.cost, HOSTED_KEY)
   })
 
   it('bills nothing for a generation stopped before fal completes it', async () => {
diff --git a/apps/sim/lib/media/falai.ts b/apps/sim/lib/media/falai.ts
index e92dadac42b..28ed99a0687 100644
--- a/apps/sim/lib/media/falai.ts
+++ b/apps/sim/lib/media/falai.ts
@@ -257,7 +257,7 @@ async function pollFalQueue(
  * Asks fal to drop a request nobody will read: a queued request never runs, and a running
  * one is signalled to stop. Best effort; the generation already failed either way.
  */
-async function cancelFalRequest(cancelUrl: string, apiKey: string, requestId: string) {
+export async function cancelFalRequest(cancelUrl: string, apiKey: string, requestId: string) {
   try {
     // boundary-raw-fetch: cancels a request on the external Fal.ai queue
     const response = await fetch(cancelUrl, {
@@ -277,8 +277,14 @@ async function cancelFalRequest(cancelUrl: string, apiKey: string, requestId: st
   }
 }
 
-/** Records a completed generation's cost; called at most once per generation. */
-export type FalCostRecorder = (cost: FalAICostMetadata) => Promise<void>
+/**
+ * Records a completed generation's cost; called at most once per generation. `envVarName` names
+ * the hosted key that ran it, so a later exact-cost settlement reads the same key.
+ */
+export type FalCostRecorder = (
+  cost: FalAICostMetadata,
+  hostedKey: { envVarName: string }
+) => Promise<void>
 
 /**
  * Bills a request fal has completed. fal charges for it whatever happens next, so the lookup
@@ -286,13 +292,13 @@ export type FalCostRecorder = (cost: FalAICostMetadata) => Promise<void>
  * the generation on our side: reading the media URL and the download a Stop can end.
  */
 export async function recordFalCost(
-  apiKey: string,
+  hostedKey: { apiKey: string; envVarName: string },
   endpointId: string,
   requestId: string,
   onCost: FalCostRecorder
 ): Promise<FalAICostMetadata> {
-  const cost = await getFalAICostMetadata({ apiKey, endpointId, requestId })
-  await onCost(cost)
+  const cost = await getFalAICostMetadata({ apiKey: hostedKey.apiKey, endpointId, requestId })
+  await onCost(cost, { envVarName: hostedKey.envVarName })
   return cost
 }
 
diff --git a/apps/sim/lib/mothership/tools/server/media/generate-audio.ts b/apps/sim/lib/mothership/tools/server/media/generate-audio.ts
index fc57fab405d..61afdeede3c 100644
--- a/apps/sim/lib/mothership/tools/server/media/generate-audio.ts
+++ b/apps/sim/lib/mothership/tools/server/media/generate-audio.ts
@@ -17,6 +17,10 @@ import {
   validateCopilotWorkspaceFileWriteTarget,
   writeCopilotWorkspaceFileByPath,
 } from '@/lib/mothership/vfs/resource-writer'
+import {
+  MOTHERSHIP_FAL_AT_COST_MULTIPLIER,
+  scheduleFalAICostSettlement,
+} from '@/lib/tools/falai-settlement'
 import { createWorkspaceFileSecretProvenanceFromRegistry } from '@/lib/uploads/contexts/workspace/file-secret-provenance'
 import { fileOperations } from '@/lib/workspace-files/application/operations'
 import { readWorkspaceFileContent } from '@/lib/workspace-files/application/read-workspace-file-content'
@@ -142,7 +146,16 @@ export const generateAudioServerTool: BaseServerTool<GenerateAudioArgs, Generate
         instrumental: params.instrumental,
         voiceSampleDataUri,
         signal: context.abortSignal,
-        onCost: (cost) => recordServiceCost('falai_audio', cost.costDollars),
+        onCost: async (cost, { envVarName }) => {
+          await recordServiceCost('falai_audio', cost.costDollars)
+          await scheduleFalAICostSettlement({
+            cost,
+            envVarName,
+            markupMultiplier: MOTHERSHIP_FAL_AT_COST_MULTIPLIER,
+            source: 'copilot',
+            billingAttribution: context.billingAttribution,
+          })
+        },
       })
 
       const ext = audioExtFromContentType(result.contentType)
diff --git a/apps/sim/lib/mothership/tools/server/media/generate-video.ts b/apps/sim/lib/mothership/tools/server/media/generate-video.ts
index 71e2f216e40..d6fc3c76c8c 100644
--- a/apps/sim/lib/mothership/tools/server/media/generate-video.ts
+++ b/apps/sim/lib/mothership/tools/server/media/generate-video.ts
@@ -17,6 +17,10 @@ import {
   validateCopilotWorkspaceFileWriteTarget,
   writeCopilotWorkspaceFileByPath,
 } from '@/lib/mothership/vfs/resource-writer'
+import {
+  MOTHERSHIP_FAL_AT_COST_MULTIPLIER,
+  scheduleFalAICostSettlement,
+} from '@/lib/tools/falai-settlement'
 import { createWorkspaceFileSecretProvenanceFromRegistry } from '@/lib/uploads/contexts/workspace/file-secret-provenance'
 import { fileOperations } from '@/lib/workspace-files/application/operations'
 import { readWorkspaceFileContent } from '@/lib/workspace-files/application/read-workspace-file-content'
@@ -119,7 +123,16 @@ export const generateVideoServerTool: BaseServerTool<GenerateVideoArgs, Generate
         promptOptimizer: params.promptOptimizer,
         imageDataUri,
         signal: context.abortSignal,
-        onCost: (cost) => recordServiceCost('falai_video', cost.costDollars),
+        onCost: async (cost, { envVarName }) => {
+          await recordServiceCost('falai_video', cost.costDollars)
+          await scheduleFalAICostSettlement({
+            cost,
+            envVarName,
+            markupMultiplier: MOTHERSHIP_FAL_AT_COST_MULTIPLIER,
+            source: 'copilot',
+            billingAttribution: context.billingAttribution,
+          })
+        },
       })
 
       assertServerToolNotAborted(context)
diff --git a/apps/sim/lib/mothership/tools/server/media/model-boundaries.test.ts b/apps/sim/lib/mothership/tools/server/media/model-boundaries.test.ts
index d1e9d401050..a43b77a66f0 100644
--- a/apps/sim/lib/mothership/tools/server/media/model-boundaries.test.ts
+++ b/apps/sim/lib/mothership/tools/server/media/model-boundaries.test.ts
@@ -39,14 +39,16 @@ import { ResolvedSecretTraceRegistry } from '@/executor/utils/resolved-secret-tr
 
 interface FalGenerationParams {
   signal?: AbortSignal
-  onCost: (cost: { costDollars: number }) => Promise<void>
+  onCost: (cost: { costDollars: number }, hostedKey: { envVarName: string }) => Promise<void>
 }
 
+const HOSTED_KEY = { envVarName: 'FALAI_API_KEY_1' }
+
 /** A fal generation that bills 0.1 through `onCost`, then returns `media` with that cost. */
 function billsThen(media: Record<string, unknown>) {
   return async ({ onCost }: FalGenerationParams) => {
     const cost = { costDollars: 0.1 }
-    await onCost(cost)
+    await onCost(cost, HOSTED_KEY)
     return { ...media, cost }
   }
 }
@@ -142,7 +144,7 @@ describe('Mothership media model boundaries', () => {
     'bills a completed %s generation once when the tool call is aborted after it',
     async (_kind, service, generator, tool) => {
       generator.mockImplementationOnce(async ({ onCost }: FalGenerationParams) => {
-        await onCost({ costDollars: 0.2 })
+        await onCost({ costDollars: 0.2 }, HOSTED_KEY)
         throw new Error('Tool timed out')
       })
       const charges = vi.fn().mockResolvedValue(undefined)
diff --git a/apps/sim/lib/mothership/tools/server/media/write-target-precheck.integration.ts b/apps/sim/lib/mothership/tools/server/media/write-target-precheck.integration.ts
index f8505521287..94ef39026ac 100644
--- a/apps/sim/lib/mothership/tools/server/media/write-target-precheck.integration.ts
+++ b/apps/sim/lib/mothership/tools/server/media/write-target-precheck.integration.ts
@@ -64,9 +64,13 @@ afterAll(async () => {
 
 /** A fal generation that bills through `onCost` before returning, as the real client does. */
 function billsThen(media: Record<string, unknown>) {
-  return async ({ onCost }: { onCost: (cost: { costDollars: number }) => Promise<void> }) => {
+  return async ({
+    onCost,
+  }: {
+    onCost: (cost: { costDollars: number }, hostedKey: { envVarName: string }) => Promise<void>
+  }) => {
     const cost = { costDollars: 0.1 }
-    await onCost(cost)
+    await onCost(cost, { envVarName: 'FALAI_API_KEY_1' })
     return { ...media, cost }
   }
 }
diff --git a/apps/sim/lib/tools/falai-pricing.ts b/apps/sim/lib/tools/falai-pricing.ts
index c5f2e54dd75..3b3a9cb22da 100644
--- a/apps/sim/lib/tools/falai-pricing.ts
+++ b/apps/sim/lib/tools/falai-pricing.ts
@@ -64,6 +64,16 @@ export interface FalAICostMetadata {
   error?: string
 }
 
+const FALAI_COST_SOURCES = new Set<string>([
+  'billing_events',
+  'historical_estimate',
+  'fallback_floor',
+])
+
+export function isFalAICostSource(value: unknown): value is FalAICostMetadata['source'] {
+  return typeof value === 'string' && FALAI_COST_SOURCES.has(value)
+}
+
 interface FalAIBillingEvent {
   request_id: string
   endpoint_id: string
diff --git a/apps/sim/lib/tools/falai-settlement.integration.ts b/apps/sim/lib/tools/falai-settlement.integration.ts
new file mode 100644
index 00000000000..1d0154df588
--- /dev/null
+++ b/apps/sim/lib/tools/falai-settlement.integration.ts
@@ -0,0 +1,175 @@
+/**
+ * The fal exact-cost settlement against a real usage ledger: a shortfall is billed once however
+ * often the settlement runs, and nothing is billed until fal records the charge. Only fal's
+ * billing-events API is stubbed.
+ */
+import { db } from '@sim/db'
+import { organization, usageLog, user, userStats } from '@sim/db/schema'
+import { generateId } from '@sim/utils/id'
+import { eq, inArray } from 'drizzle-orm'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { type FalAICostSettlementPayload, settleFalAICost } from '@/lib/tools/falai-settlement'
+
+const HOSTED_KEY_ENV_VAR = 'FALAI_API_KEY_1'
+const userIds: string[] = []
+const organizationIds: string[] = []
+
+async function createUser(): Promise<string> {
+  const id = `falai-settlement-user-${generateId()}`
+  const now = new Date()
+  await db.insert(user).values({
+    id,
+    name: 'Fal Settlement Test',
+    email: `${id}@falai-settlement.test`,
+    emailVerified: true,
+    createdAt: now,
+    updatedAt: now,
+  })
+  await db.insert(userStats).values({ id: generateId(), userId: id })
+  userIds.push(id)
+  return id
+}
+
+async function createOrganization(): Promise<string> {
+  const id = `falai-settlement-org-${generateId()}`
+  await db.insert(organization).values({ id, name: 'Fal Settlement Org', slug: id })
+  organizationIds.push(id)
+  return id
+}
+
+/** A settlement billed to an organization payer, the snapshot shape for a run outside a workspace. */
+function payloadFor(
+  userId: string,
+  organizationId: string,
+  billedProviderCostDollars: number,
+  billingPeriod = { start: '2026-11-01T00:00:00.000Z', end: '2026-12-01T00:00:00.000Z' }
+): FalAICostSettlementPayload {
+  return {
+    envVarName: HOSTED_KEY_ENV_VAR,
+    endpointId: 'bytedance/seedance-2.5/text-to-video',
+    requestId: `fal-request-${generateId()}`,
+    billedProviderCostDollars,
+    markupMultiplier: 1.5,
+    ledger: {
+      source: 'workflow',
+      billingAttribution: {
+        actorUserId: userId,
+        workspaceId: null,
+        organizationId,
+        billedAccountUserId: userId,
+        billingEntity: { type: 'organization', id: organizationId },
+        billingPeriod,
+        payerSubscription: null,
+      },
+    },
+  }
+}
+
+/** fal's billing-events API answering with the charge for `requestId`, or with none yet. */
+function stubFalBillingEvents(charge: { requestId: string; costDollars: number } | null) {
+  const fetchMock = vi.fn(async () =>
+    Response.json({
+      billing_events: charge
+        ? [
+            {
+              request_id: charge.requestId,
+              endpoint_id: 'bytedance/seedance-2.5/text-to-video',
+              output_units: 700,
+              unit_price: 0.0214,
+              percent_discount: null,
+              cost_estimate_nano_usd: Math.round(charge.costDollars * 1_000_000_000),
+            },
+          ]
+        : [],
+    })
+  )
+  vi.stubGlobal('fetch', fetchMock)
+  return fetchMock
+}
+
+async function settlementRows(userId: string) {
+  return db
+    .select({
+      cost: usageLog.cost,
+      description: usageLog.description,
+      source: usageLog.source,
+      billingPeriodEnd: usageLog.billingPeriodEnd,
+    })
+    .from(usageLog)
+    .where(eq(usageLog.userId, userId))
+}
+
+beforeEach(() => {
+  vi.stubEnv(HOSTED_KEY_ENV_VAR, 'hosted-fixture-key')
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.unstubAllEnvs()
+})
+
+afterAll(async () => {
+  if (userIds.length > 0) {
+    await db.delete(usageLog).where(inArray(usageLog.userId, userIds))
+    await db.delete(user).where(inArray(user.id, userIds))
+  }
+  if (organizationIds.length > 0) {
+    await db.delete(organization).where(inArray(organization.id, organizationIds))
+  }
+})
+
+describe('settleFalAICost', () => {
+  it('bills the shortfall once when the exact charge exceeds the estimate, however often it runs', async () => {
+    const userId = await createUser()
+    const organizationId = await createOrganization()
+    const payload = payloadFor(userId, organizationId, 6.49)
+    stubFalBillingEvents({ requestId: payload.requestId, costDollars: 15 })
+
+    expect(await settleFalAICost(payload)).toBe('charged')
+    expect(await settleFalAICost(payload)).toBe('charged')
+
+    const rows = await settlementRows(userId)
+    expect(rows).toHaveLength(1)
+    expect(Number(rows[0].cost)).toBeCloseTo((15 - 6.49) * 1.5, 6)
+    expect(rows[0]).toMatchObject({
+      source: 'workflow',
+      description: 'fal exact cost settlement: bytedance/seedance-2.5/text-to-video',
+    })
+  })
+
+  it('bills a settlement that outlives its billing period to the payer current period', async () => {
+    const userId = await createUser()
+    const organizationId = await createOrganization()
+    const endedPeriod = { start: '2026-01-01T00:00:00.000Z', end: '2026-02-01T00:00:00.000Z' }
+    const payload = payloadFor(userId, organizationId, 6.49, endedPeriod)
+    stubFalBillingEvents({ requestId: payload.requestId, costDollars: 15 })
+
+    expect(await settleFalAICost(payload)).toBe('charged')
+
+    const rows = await settlementRows(userId)
+    expect(rows).toHaveLength(1)
+    expect(rows[0].billingPeriodEnd?.getTime()).toBeGreaterThan(Date.now())
+  })
+
+  it('bills nothing while fal has not recorded the charge', async () => {
+    const userId = await createUser()
+    const organizationId = await createOrganization()
+    stubFalBillingEvents(null)
+
+    expect(await settleFalAICost(payloadFor(userId, organizationId, 0.25))).toBe('pending')
+
+    expect(await settlementRows(userId)).toHaveLength(0)
+  })
+
+  it('refuses to settle when the hosted key that ran the request is not configured', async () => {
+    const userId = await createUser()
+    const organizationId = await createOrganization()
+    vi.stubEnv(HOSTED_KEY_ENV_VAR, '')
+    const fetchMock = stubFalBillingEvents(null)
+
+    await expect(settleFalAICost(payloadFor(userId, organizationId, 6.49))).rejects.toThrow(
+      'Hosted fal key FALAI_API_KEY_1 is not configured'
+    )
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+})
diff --git a/apps/sim/lib/tools/falai-settlement.ts b/apps/sim/lib/tools/falai-settlement.ts
new file mode 100644
index 00000000000..819e763c04c
--- /dev/null
+++ b/apps/sim/lib/tools/falai-settlement.ts
@@ -0,0 +1,176 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { tasks } from '@trigger.dev/sdk'
+import {
+  type BillingAttributionSnapshot,
+  refreshAttributionPeriod,
+} from '@/lib/billing/core/attribution'
+import { recordUsage, stableEventKey } from '@/lib/billing/core/usage-log'
+import { resolveTriggerRegion } from '@/lib/core/async-jobs/region'
+import { env } from '@/lib/core/config/env'
+import { isBillingEnabled, isHosted, isTriggerDevEnabled } from '@/lib/core/config/env-flags'
+import { type FalAICostMetadata, getFalAIBillingReceipt } from '@/lib/tools/falai-pricing'
+
+const logger = createLogger('FalAICostSettlement')
+
+export const FALAI_COST_SETTLEMENT_TASK_ID = 'falai-cost-settlement' as const
+
+/** fal records a request's billing event after it completes; the first look waits this long. */
+const FALAI_SETTLEMENT_DELAY = '2m'
+
+/** Mothership bills fal media at cost, so a Chat generation settles without markup. */
+export const MOTHERSHIP_FAL_AT_COST_MULTIPLIER = 1
+
+/** Ledger sources a hosted fal charge can be billed under. */
+type FalAISettlementSource = 'workflow' | 'copilot' | 'api-tool'
+
+/**
+ * Everything a settlement needs once the generation's run is gone. The hosted key travels as
+ * its env var name, never its value, so the task reads the same key that created the request.
+ */
+export interface FalAICostSettlementPayload {
+  envVarName: string
+  endpointId: string
+  requestId: string
+  /** The provider cost billed at completion, before markup. */
+  billedProviderCostDollars: number
+  markupMultiplier: number
+  ledger: {
+    source: FalAISettlementSource
+    workflowId?: string
+    executionId?: string
+    /** The run's payer as admitted; its period is refreshed when settlement outlives it. */
+    billingAttribution: BillingAttributionSnapshot
+  }
+}
+
+/** The outcome of one settlement attempt. `pending` means fal has not recorded the charge yet. */
+type FalAICostSettlementOutcome = 'pending' | 'charged' | 'exact' | 'overbilled'
+
+interface ScheduleFalAICostSettlementParams {
+  cost: Pick<FalAICostMetadata, 'endpointId' | 'requestId' | 'costDollars' | 'source'>
+  envVarName: string
+  markupMultiplier: number
+  source: FalAISettlementSource
+  /** The run's payer; a run without one is billed on its estimate. */
+  billingAttribution: BillingAttributionSnapshot | undefined
+  workflowId?: string
+  executionId?: string
+}
+
+/**
+ * Schedules the exact-cost settlement for a hosted fal generation billed on an estimate. A
+ * generation billed from its own receipt is already exact and schedules nothing. Settlement only
+ * adds what the estimate missed, so a failure here leaves the estimate billed and never fails
+ * the generation.
+ */
+export async function scheduleFalAICostSettlement(
+  params: ScheduleFalAICostSettlementParams
+): Promise<void> {
+  const { cost, billingAttribution } = params
+  if (!isHosted || !isBillingEnabled) return
+  if (cost.source === 'billing_events' || !billingAttribution) return
+  if (!isTriggerDevEnabled || !env.TRIGGER_SECRET_KEY) {
+    logger.warn('Trigger.dev not configured; fal charge stays on its estimate', {
+      endpointId: cost.endpointId,
+      requestId: cost.requestId,
+    })
+    return
+  }
+
+  const payload: FalAICostSettlementPayload = {
+    envVarName: params.envVarName,
+    endpointId: cost.endpointId,
+    requestId: cost.requestId,
+    billedProviderCostDollars: cost.costDollars,
+    markupMultiplier: params.markupMultiplier,
+    ledger: {
+      source: params.source,
+      workflowId: params.workflowId,
+      executionId: params.executionId,
+      billingAttribution,
+    },
+  }
+
+  try {
+    await tasks.trigger(FALAI_COST_SETTLEMENT_TASK_ID, payload, {
+      delay: FALAI_SETTLEMENT_DELAY,
+      idempotencyKey: `falai-cost-settlement-${cost.requestId}`,
+      region: await resolveTriggerRegion(),
+    })
+  } catch (error) {
+    logger.warn('Failed to schedule the fal exact-cost settlement; the estimate stays billed', {
+      endpointId: cost.endpointId,
+      requestId: cost.requestId,
+      error: getErrorMessage(error),
+    })
+  }
+}
+
+/**
+ * Bills the difference between fal's exact charge for a request and the estimate billed at
+ * completion. The ledger row's event key is the request, so a retried settlement never bills
+ * twice. An estimate above the exact charge is left as billed: the ledger records charges only.
+ * A settlement that outlives the run's billing period bills the payer's current period, since
+ * the ended one may already be closed and invoiced.
+ */
+export async function settleFalAICost(
+  payload: FalAICostSettlementPayload
+): Promise<FalAICostSettlementOutcome> {
+  const { envVarName, endpointId, requestId, billedProviderCostDollars, markupMultiplier, ledger } =
+    payload
+  const apiKey = process.env[envVarName]
+  if (!apiKey) throw new Error(`Hosted fal key ${envVarName} is not configured`)
+
+  const receipt = await getFalAIBillingReceipt({ apiKey, endpointId, requestId })
+  if (!receipt) return 'pending'
+
+  const shortfallDollars = (receipt.costDollars - billedProviderCostDollars) * markupMultiplier
+  if (shortfallDollars < 0) {
+    logger.info('fal estimate exceeded the exact charge', {
+      endpointId,
+      requestId,
+      overbilledDollars: -shortfallDollars,
+    })
+    return 'overbilled'
+  }
+  if (shortfallDollars === 0) return 'exact'
+
+  const attribution =
+    Date.parse(ledger.billingAttribution.billingPeriod.end) <= Date.now()
+      ? await refreshAttributionPeriod(ledger.billingAttribution)
+      : ledger.billingAttribution
+  await recordUsage({
+    userId: attribution.actorUserId,
+    workspaceId: attribution.workspaceId ?? undefined,
+    workflowId: ledger.workflowId,
+    executionId: ledger.executionId,
+    billingEntity: { ...attribution.billingEntity },
+    billingPeriod: {
+      start: new Date(attribution.billingPeriod.start),
+      end: new Date(attribution.billingPeriod.end),
+    },
+    entries: [
+      {
+        category: 'tool',
+        source: ledger.source,
+        description: `fal exact cost settlement: ${endpointId}`,
+        cost: shortfallDollars,
+        eventKey: stableEventKey({ kind: 'falai-cost-settlement', requestId }),
+        metadata: {
+          endpointId,
+          requestId,
+          billedProviderCostDollars,
+          exactProviderCostDollars: receipt.costDollars,
+          markupMultiplier,
+        },
+      },
+    ],
+  })
+  logger.info('Settled fal charge to its exact cost', {
+    endpointId,
+    requestId,
+    shortfallDollars,
+  })
+  return 'charged'
+}
diff --git a/apps/sim/tools/image/generate.ts b/apps/sim/tools/image/generate.ts
index 0c9257c6e51..7226e12b41a 100644
--- a/apps/sim/tools/image/generate.ts
+++ b/apps/sim/tools/image/generate.ts
@@ -127,6 +127,7 @@ export const imageGenerateTool: ImageGenerationToolConfig = {
     envKeyPrefix: 'FALAI_API_KEY',
     apiKeyParam: 'apiKey',
     byokProviderId: 'falai',
+    exactCostSettlement: 'falai',
     pricing: {
       type: 'custom',
       getCost: (_params, output) => {
diff --git a/apps/sim/tools/index.test.ts b/apps/sim/tools/index.test.ts
index fd6f413a055..b4495864fdf 100644
--- a/apps/sim/tools/index.test.ts
+++ b/apps/sim/tools/index.test.ts
@@ -116,8 +116,10 @@ const {
   mockGetInternalToolOperationHandler,
   mockExecuteInternalToolOperation,
   mockPayerHasPaidAccess,
+  mockScheduleFalAICostSettlement,
 } = vi.hoisted(() => ({
   mockPayerHasPaidAccess: vi.fn(),
+  mockScheduleFalAICostSettlement: vi.fn(),
   mockGetToolAsync: vi.fn(),
   mockRateLimiterFns: {
     acquireKey: vi.fn(),
@@ -183,6 +185,10 @@ vi.mock('@/lib/billing/core/chat-access', () => ({
   payerHasPaidAccess: mockPayerHasPaidAccess,
 }))
 
+vi.mock('@/lib/tools/falai-settlement', () => ({
+  scheduleFalAICostSettlement: mockScheduleFalAICostSettlement,
+}))
+
 vi.mock('@/lib/billing/core/attribution', () => billingAttributionMock)
 
 vi.mock('@/lib/uploads/contexts/workspace/file-manager', () => workspaceFileManagerMock)
@@ -6564,6 +6570,74 @@ describe('Hosted Key Injection', () => {
     }
   })
 
+  it('schedules the exact-cost settlement for a hosted fal charge estimated at zero', async () => {
+    setEnvFlags({ isHosted: true })
+    mockGetBYOKKey.mockResolvedValue(null)
+    mockRateLimiterFns.acquireKey.mockResolvedValue({
+      success: true,
+      key: 'platform-fixture-key',
+      keyIndex: 0,
+      envVarName: 'FALAI_API_KEY_1',
+    })
+    mockValidateUrlWithDNS.mockResolvedValue({ isValid: true, resolvedIP: '93.184.216.34' })
+    mockSecureFetchWithPinnedIP.mockResolvedValue({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      headers: { get: () => null, toRecord: () => ({}) },
+      json: async () => ({ ok: true }),
+      text: async () => '{"ok":true}',
+    })
+    tools.test_fal_zero_estimate = {
+      id: 'test_fal_zero_estimate',
+      name: 'Zero-estimate fal fixture',
+      description: 'Hosted fal charge whose estimate is zero',
+      version: '1.0.0',
+      params: {},
+      request: { url: 'https://example.com/fixture', method: 'GET', headers: () => ({}) },
+      hosting: {
+        envKeyPrefix: 'FALAI_API_KEY',
+        apiKeyParam: 'apiKey',
+        byokProviderId: 'falai',
+        exactCostSettlement: 'falai',
+        pricing: {
+          type: 'custom',
+          getCost: () => ({
+            cost: 0,
+            metadata: {
+              endpointId: 'fal-ai/fixture/text-to-video',
+              requestId: 'fal-request-1',
+              source: 'historical_estimate',
+              providerCostDollars: 0,
+              markupMultiplier: 1.5,
+            },
+          }),
+        },
+        rateLimit: { mode: 'per_request', requestsPerMinute: 100 },
+      },
+      transformResponse: async () => ({ success: true, output: {} }),
+    }
+    try {
+      const result = await executeTool(
+        'test_fal_zero_estimate',
+        {},
+        { executionContext: createToolExecutionContext({ userId: 'user-1' }) }
+      )
+
+      expect(result.success).toBe(true)
+      expect(mockScheduleFalAICostSettlement).toHaveBeenCalledWith(
+        expect.objectContaining({
+          cost: expect.objectContaining({ requestId: 'fal-request-1', costDollars: 0 }),
+          envVarName: 'FALAI_API_KEY_1',
+          source: 'workflow',
+        })
+      )
+    } finally {
+      Reflect.deleteProperty(tools, 'test_fal_zero_estimate')
+      resetEnvFlagsMock()
+    }
+  })
+
   describe('requiresPaidPlan', () => {
     const PAID_ONLY_TOOL_ID = 'test_paid_only_hosting'
 
diff --git a/apps/sim/tools/index.ts b/apps/sim/tools/index.ts
index 05dff63008e..cfc9708c3cc 100644
--- a/apps/sim/tools/index.ts
+++ b/apps/sim/tools/index.ts
@@ -1,5 +1,6 @@
 import { createLogger } from '@sim/logger'
 import { isLoopbackIp, unwrapIpv6Brackets } from '@sim/security/ssrf'
+import { toNumberOrNull, toStringOrNull } from '@sim/utils/coerce'
 import { describeError, getErrorMessage, toError } from '@sim/utils/errors'
 import { sleep } from '@sim/utils/helpers'
 import { isPlainRecord, isRecordLike, toRecord } from '@sim/utils/object'
@@ -99,6 +100,8 @@ import {
 } from '@/lib/mothership/billing/service-observer'
 import { CredentialRevokedError } from '@/lib/oauth/credential-revoked'
 import type { CredentialTokenPayload } from '@/lib/oauth/token-resolution'
+import { isFalAICostSource } from '@/lib/tools/falai-pricing'
+import { scheduleFalAICostSettlement } from '@/lib/tools/falai-settlement'
 import { resolveWorkspaceFileReference } from '@/lib/uploads/contexts/workspace/file-manager'
 import { markWorkspaceFileSecretProvenanceUnknown } from '@/lib/uploads/contexts/workspace/file-secret-provenance'
 import { MAX_FILE_SIZE } from '@/lib/uploads/utils/validation'
@@ -954,7 +957,7 @@ async function processHostedKeyCost(
 
   const { cost, metadata } = calculateToolCost(tool.hosting.pricing, params, response, tool.id)
 
-  if (cost <= 0) return { cost: 0 }
+  if (cost <= 0) return { cost: 0, metadata }
 
   logger.debug(`Hosted key cost for ${tool.id}: $${cost}`, metadata ? { metadata } : {}, {
     requestId,
@@ -1028,6 +1031,49 @@ export function postProcessToolOutput(toolId: string, output: Record<string, unk
   return isCustomTool(toolId) ? output : stripInternalFields(output)
 }
 
+/**
+ * Schedules the exact-cost settlement for a hosted charge billed before the provider recorded
+ * its receipt, for a tool whose hosting declares one.
+ */
+async function scheduleExactCostSettlement(
+  tool: ToolDefinition,
+  metadata: Record<string, unknown> | undefined,
+  scope: ToolExecutionScope,
+  envVarName: string | undefined
+): Promise<void> {
+  if (tool.hosting?.exactCostSettlement !== 'falai' || !envVarName) return
+  const endpointId = toStringOrNull(metadata?.endpointId)
+  const falRequestId = toStringOrNull(metadata?.requestId)
+  const costSource = metadata?.source
+  const providerCostDollars = toNumberOrNull(metadata?.providerCostDollars)
+  const markupMultiplier = toNumberOrNull(metadata?.markupMultiplier)
+  if (
+    !endpointId ||
+    !falRequestId ||
+    !isFalAICostSource(costSource) ||
+    providerCostDollars === null ||
+    markupMultiplier === null
+  ) {
+    return
+  }
+
+  const { billingAttribution, copilotToolExecution, workflowId, executionId } = scope
+  await scheduleFalAICostSettlement({
+    cost: {
+      endpointId,
+      requestId: falRequestId,
+      costDollars: providerCostDollars,
+      source: costSource,
+    },
+    envVarName,
+    markupMultiplier,
+    source: copilotToolExecution ? 'copilot' : executionId ? 'workflow' : 'api-tool',
+    billingAttribution,
+    workflowId,
+    executionId,
+  })
+}
+
 /**
  * Apply post-execution hosted-key cost tracking to a successful tool result.
  * Reports custom dimension usage, calculates cost, and merges it into the output.
@@ -1080,8 +1126,12 @@ async function applyHostedKeyCostToResult(
   hostedKeyMetrics.recordUsed({ provider, tool: tool.id, key })
   hostedKeyMetrics.recordCostCharged(hostedKeyCost, { provider, tool: tool.id })
 
+  const scope = resolveToolScope(params, executionContext)
+  // A zero estimate is not proof the generation was free; settlement bills the receipt.
+  await scheduleExactCostSettlement(tool, metadata, scope, envVarName)
+
   if (hostedKeyCost > 0) {
-    const { copilotToolExecution } = resolveToolScope(params, executionContext)
+    const { copilotToolExecution } = scope
     if (copilotToolExecution) await recordServiceCost(provider, hostedKeyCost)
     finalResult.output = {
       ...finalResult.output,
diff --git a/apps/sim/tools/types.ts b/apps/sim/tools/types.ts
index 17f2bff890b..c013e7b6121 100644
--- a/apps/sim/tools/types.ts
+++ b/apps/sim/tools/types.ts
@@ -505,6 +505,11 @@ export interface ToolHostingConfig<P = Record<string, unknown>> {
    * or a key the user passes still runs; only Sim's own key is refused.
    */
   requiresPaidPlan?: boolean
+  /**
+   * Bills the hosted charge again from the provider's exact receipt once it is recorded, for a
+   * provider whose receipt arrives after the result. `falai` settles through fal's billing events.
+   */
+  exactCostSettlement?: 'falai'
   /** Pricing when using hosted key */
   pricing: ToolHostingPricing<P>
   /** Hosted key rate limit configuration (required for hosted key distribution) */
diff --git a/apps/sim/tools/video/falai.ts b/apps/sim/tools/video/falai.ts
index 1c8907eb184..be34f58fd0f 100644
--- a/apps/sim/tools/video/falai.ts
+++ b/apps/sim/tools/video/falai.ts
@@ -71,6 +71,7 @@ export const falaiVideoTool: InternalToolConfig<VideoParams, VideoResponse> = {
     envKeyPrefix: 'FALAI_API_KEY',
     apiKeyParam: 'apiKey',
     byokProviderId: 'falai',
+    exactCostSettlement: 'falai',
     requiresPaidPlan: true,
     pricing: {
       type: 'custom',