@ossy/platform 3.20.0 → 3.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/platform",
-  "version": "3.20.0",
+  "version": "3.20.1",
   "description": "Ossy application server runtime",
   "repository": {
     "type": "git",
@@ -48,17 +48,17 @@
     "@aws-sdk/util-format-url": "^3.972.17",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@ossy/config": "^3.0.9",
-    "@ossy/event-store": "^3.20.0",
+    "@ossy/event-store": "^3.20.1",
     "@ossy/locale": "^3.4.0",
-    "@ossy/manifest": "^3.20.0",
+    "@ossy/manifest": "^3.20.1",
     "@ossy/observability": "^3.0.9",
     "@ossy/policies": "^3.0.9",
     "@ossy/router": "^3.0.9",
-    "@ossy/schema": "^3.20.0",
-    "@ossy/sdk": "^3.20.0",
+    "@ossy/schema": "^3.20.1",
+    "@ossy/sdk": "^3.20.1",
     "@ossy/tokens": "^3.11.1",
-    "@ossy/users": "^3.20.0",
-    "@ossy/workspaces": "^3.20.0",
+    "@ossy/users": "^3.20.1",
+    "@ossy/workspaces": "^3.20.1",
     "cookie-parser": "^1.4.7",
     "dotenv": ">=16.0.0 <18.0.0",
     "express": ">=5.0.0 <6.0.0",
@@ -79,5 +79,5 @@
     "Dockerfile",
     "docker-healthcheck.js"
   ],
-  "gitHead": "edab6a966f41c07a68bdd86f3864cc2ad02e3406"
+  "gitHead": "3e8bb118b3ef163792a004663ccb803ab51a8601"
 }

package/src/index.js

@@ -1,5 +1,5 @@
 export { TaskService } from './tasks/task-service.js'
-export { createInProcessSdk } from './tasks/in-process-sdk.js'
+export { createInProcessSdk, botReq, resolveBotReq } from './tasks/in-process-sdk.js'
 export { loadAndRegisterTasks } from './tasks/task-registry.js'
 export { ChangeStream } from './tasks/change-stream.js'
 export { registerSchema, getSystemSchemas } from './resources/schema.registry.js'

package/src/server.js

@@ -284,7 +284,7 @@ export async function startServer (options = {}) {
   const layoutsById = await loadLayoutsById(layoutManifest, buildDir, log)
 
   // Register the SDK so all tasks receive it as `sdk`.
-  // Priority: explicit options.sdk → HTTP bot SDK (API_URL + OSSY_API_KEY) → in-process ActionService SDK.
+  // Priority: explicit options.sdk → HTTP bot SDK (API_URL + OSSY_API_KEY) → in-process ActionService SDK as the bot user.
   const botSdk = (process.env.API_URL && process.env.OSSY_API_KEY)
     ? SDK.of({ apiUrl: process.env.API_URL, authorization: process.env.OSSY_API_KEY })
     : null
@@ -727,6 +727,7 @@ export default startServer
 export { loadLayoutsById, resolvePageLayoutRender }
 export { ConfigService } from './config.service.js'
 export { ActionService } from './actions/action.service.js'
+export { createInProcessSdk, botReq, resolveBotReq } from './tasks/in-process-sdk.js'
 export { applyVerifySignInSessionCookies } from './verify-sign-in-session.js'
 export { IntegrationService } from './integration.service.js'
 export { StorageClient } from './storage/storage.client.js'

package/src/tasks/change-stream.js

@@ -11,13 +11,19 @@ function isMongoTopologyClosedError(error) {
   return false
 }
 
-/** Watches `eventstore` inserts. Uses the shared {@link Mongo} client — one per process. */
+/** Watches `eventstore` inserts. Uses the shared {@link Mongo} client — one per process.
+ *  Every `startServer` with `DB_URL` opens its own watch; TaskService uses Mongo claims
+ *  so only one process runs a given trigger (#982 / ADR 0019). */
 export class ChangeStream {
 
   static _stopped = false
   static _reconnectAttempts = 0
   /** @type {import('mongodb').ChangeStream | null} */
   static _changeStream = null
+  /** @type {Set<import('mongodb').ChangeStream>} */
+  static _streams = new Set()
+  /** @type {Promise<void> | null} */
+  static _openPromise = null
   /** @type {ReturnType<typeof setTimeout> | null} */
   static _reconnectTimer = null
 
@@ -39,15 +45,7 @@ export class ChangeStream {
       ChangeStream._reconnectTimer = null
     }
 
-    const stream = ChangeStream._changeStream
-    ChangeStream._changeStream = null
-    if (stream) {
-      try {
-        await stream.close()
-      } catch {
-        // ignore — stream may already be closed
-      }
-    }
+    await ChangeStream._closeStreams()
 
     log.info('[ChangeStream] Stopped')
   }
@@ -87,7 +85,33 @@ export class ChangeStream {
     }, delaySecs * 1000)
   }
 
-  static async _open () {
+  static _open () {
+    if (ChangeStream._stopped) return Promise.resolve()
+    if (ChangeStream._openPromise) return ChangeStream._openPromise
+    ChangeStream._openPromise = ChangeStream._openNow().finally(() => {
+      ChangeStream._openPromise = null
+    })
+    return ChangeStream._openPromise
+  }
+
+  /**
+   * Close every live cursor. Streams we close here must not schedule a reconnect.
+   */
+  static async _closeStreams () {
+    const streams = [...ChangeStream._streams]
+    ChangeStream._streams.clear()
+    ChangeStream._changeStream = null
+    await Promise.all(streams.map(async (stream) => {
+      stream.replaced = true
+      try {
+        await stream.close()
+      } catch {
+        // ignore — stream may already be closed
+      }
+    }))
+  }
+
+  static async _openNow () {
     if (ChangeStream._stopped) return
 
     log.info('[ChangeStream] Watching for changes')
@@ -98,18 +122,13 @@ export class ChangeStream {
 
     const collection = client.db(dbName).collection('eventstore')
 
-    if (ChangeStream._changeStream) {
-      try {
-        await ChangeStream._changeStream.close()
-      } catch {
-        // ignore
-      }
-      ChangeStream._changeStream = null
-    }
+    await ChangeStream._closeStreams()
+    if (ChangeStream._stopped) return
 
     const changeStream = collection.watch([
       { $match: { operationType: 'insert' } },
     ])
+    ChangeStream._streams.add(changeStream)
     ChangeStream._changeStream = changeStream
 
     const wasReconnecting = ChangeStream._reconnectAttempts > 0
@@ -129,7 +148,7 @@ export class ChangeStream {
     }
 
     changeStream.on('error', (error) => {
-      if (ChangeStream._stopped) return
+      if (changeStream.replaced || ChangeStream._stopped) return
       log.error('[ChangeStream] Change stream error (server keeps running)', undefined, error)
       if (isMongoTopologyClosedError(error)) {
         ChangeStream._resetSharedClient()
@@ -149,23 +168,18 @@ export class ChangeStream {
       TaskService.dispatch(event)
     })
 
-    changeStream.on('close', () => {
+    const drop = (label) => {
+      ChangeStream._streams.delete(changeStream)
       if (ChangeStream._changeStream === changeStream) {
         ChangeStream._changeStream = null
       }
-      if (ChangeStream._stopped) return
-      log.info('[ChangeStream] close detected')
+      if (changeStream.replaced || ChangeStream._stopped) return
+      log.info(`[ChangeStream] ${label} detected`)
       scheduleOnce()
-    })
+    }
 
-    changeStream.on('end', () => {
-      if (ChangeStream._changeStream === changeStream) {
-        ChangeStream._changeStream = null
-      }
-      if (ChangeStream._stopped) return
-      log.info('[ChangeStream] end detected')
-      scheduleOnce()
-    })
+    changeStream.on('close', () => drop('close'))
+    changeStream.on('end', () => drop('end'))
   }
 
 }

package/src/tasks/dispatch-claim.js

@@ -0,0 +1,116 @@
+import os from 'node:os'
+import { Mongo, withMongoReconnect } from '@ossy/event-store'
+import { createLogger } from '@ossy/observability'
+
+const log = createLogger('platform/dispatch-claim')
+
+export const DISPATCH_CLAIM_COLLECTION = 'task_dispatch_claims'
+export const DEFAULT_CLAIM_TTL_MS = 15 * 60 * 1000
+
+/** @type {null | { insertOne: Function, findOneAndUpdate: Function }} */
+let _collectionOverride = null
+
+/**
+ * @param {null | { insertOne: Function, findOneAndUpdate: Function }} collection
+ */
+export function setDispatchClaimCollectionForTests (collection) {
+  _collectionOverride = collection
+}
+
+function getCollection () {
+  if (_collectionOverride) return _collectionOverride
+  return Mongo.db.collection(DISPATCH_CLAIM_COLLECTION)
+}
+
+/**
+ * Natural key for event-triggered task runs (changestream / TaskService.dispatch).
+ *
+ * @param {string} taskId
+ * @param {string | null | undefined} eventId
+ * @returns {string | null}
+ */
+export function buildEventClaimKey (taskId, eventId) {
+  if (!taskId || !eventId) return null
+  return `event:${taskId}:${eventId}`
+}
+
+/**
+ * Natural key for cron/schedule ticks (one claim per task+workspace+UTC minute).
+ *
+ * @param {string} taskId
+ * @param {string | null | undefined} workspaceId
+ * @param {Date} [at]
+ * @returns {string | null}
+ */
+export function buildScheduleClaimKey (taskId, workspaceId, at = new Date()) {
+  if (!taskId) return null
+  const minute = at.toISOString().slice(0, 16)
+  const ws = workspaceId || '_'
+  return `schedule:${taskId}:${ws}:${minute}`
+}
+
+/**
+ * Natural key for on_action follow-ups when an actionInvocationId is present.
+ *
+ * @param {string} taskId
+ * @param {string | null | undefined} actionInvocationId
+ * @returns {string | null}
+ */
+export function buildActionClaimKey (taskId, actionInvocationId) {
+  if (!taskId || !actionInvocationId) return null
+  return `action:${taskId}:${actionInvocationId}`
+}
+
+function defaultHolder () {
+  return `${os.hostname()}:${process.pid}`
+}
+
+/**
+ * Try to exclusively claim a dispatch key across platform processes sharing Mongo.
+ *
+ * - Missing key → allow (caller has no natural id; e.g. invoke without claim).
+ * - First insert wins; expired claims can be stolen.
+ * - Fail closed on unexpected Mongo errors (skip the run rather than double-run).
+ *
+ * @param {string | null | undefined} key
+ * @param {{ holder?: string, ttlMs?: number }} [opts]
+ * @returns {Promise<boolean>}
+ */
+export async function tryClaimDispatch (key, opts = {}) {
+  if (!key) return true
+
+  const holder = opts.holder ?? defaultHolder()
+  const ttlMs = opts.ttlMs ?? DEFAULT_CLAIM_TTL_MS
+  const now = new Date()
+  const expiresAt = new Date(now.getTime() + ttlMs)
+  const doc = { _id: key, holder, claimedAt: now, expiresAt }
+
+  const attempt = async () => {
+    const col = getCollection()
+    try {
+      await col.insertOne(doc)
+      return true
+    } catch (err) {
+      if (err?.code !== 11000) throw err
+
+      const stolen = await col.findOneAndUpdate(
+        { _id: key, expiresAt: { $lte: now } },
+        { $set: { holder, claimedAt: now, expiresAt } },
+        { returnDocument: 'after' },
+      )
+      // Driver v4 returns `{ value }`; v6 may return the document or null.
+      const value = stolen && typeof stolen === 'object' && 'value' in stolen
+        ? stolen.value
+        : stolen
+      return Boolean(value)
+    }
+  }
+
+  try {
+    if (_collectionOverride) return await attempt()
+    return await withMongoReconnect(attempt)
+  } catch (err) {
+    log.warn(`[dispatch-claim] claim failed for ${key}; skipping run`, { key }, err)
+    return false
+  }
+}

package/src/tasks/dispatch-claim.spec.js

@@ -0,0 +1,82 @@
+import { describe, expect, it, beforeEach, afterEach } from '@jest/globals'
+import {
+  buildActionClaimKey,
+  buildEventClaimKey,
+  buildScheduleClaimKey,
+  setDispatchClaimCollectionForTests,
+  tryClaimDispatch,
+} from './dispatch-claim.js'
+
+describe('dispatch-claim keys', () => {
+  it('builds event and action keys', () => {
+    expect(buildEventClaimKey('@ossy/x/tasks/y', 'evt1')).toBe('event:@ossy/x/tasks/y:evt1')
+    expect(buildEventClaimKey('@ossy/x/tasks/y', null)).toBe(null)
+    expect(buildActionClaimKey('@ossy/x/tasks/y', 'inv1')).toBe('action:@ossy/x/tasks/y:inv1')
+    expect(buildActionClaimKey('@ossy/x/tasks/y', null)).toBe(null)
+  })
+
+  it('builds schedule keys per UTC minute and workspace', () => {
+    const at = new Date('2026-10-01T09:15:42.123Z')
+    expect(buildScheduleClaimKey('@ossy/x/tasks/y', 'ws1', at))
+      .toBe('schedule:@ossy/x/tasks/y:ws1:2026-10-01T09:15')
+    expect(buildScheduleClaimKey('@ossy/x/tasks/y', null, at))
+      .toBe('schedule:@ossy/x/tasks/y:_:2026-10-01T09:15')
+  })
+})
+
+describe('tryClaimDispatch', () => {
+  /** @type {Map<string, object>} */
+  let store
+
+  beforeEach(() => {
+    store = new Map()
+    setDispatchClaimCollectionForTests({
+      async insertOne (doc) {
+        if (store.has(doc._id)) {
+          const err = new Error('E11000 duplicate key')
+          err.code = 11000
+          throw err
+        }
+        store.set(doc._id, { ...doc })
+        return { acknowledged: true }
+      },
+      async findOneAndUpdate (filter, update) {
+        const existing = store.get(filter._id)
+        if (!existing) return null
+        if (filter.expiresAt?.$lte && !(existing.expiresAt <= filter.expiresAt.$lte)) {
+          return null
+        }
+        const next = { ...existing, ...update.$set }
+        store.set(filter._id, next)
+        return next
+      },
+    })
+  })
+
+  afterEach(() => {
+    setDispatchClaimCollectionForTests(null)
+  })
+
+  it('allows when key is missing', async () => {
+    expect(await tryClaimDispatch(null)).toBe(true)
+    expect(await tryClaimDispatch(undefined)).toBe(true)
+  })
+
+  it('first claim wins; second loses until expiry', async () => {
+    expect(await tryClaimDispatch('event:t:e1', { holder: 'a' })).toBe(true)
+    expect(await tryClaimDispatch('event:t:e1', { holder: 'b' })).toBe(false)
+    expect(store.get('event:t:e1').holder).toBe('a')
+  })
+
+  it('expired claim can be stolen', async () => {
+    const past = new Date(Date.now() - 60_000)
+    store.set('event:t:e2', {
+      _id: 'event:t:e2',
+      holder: 'old',
+      claimedAt: past,
+      expiresAt: past,
+    })
+    expect(await tryClaimDispatch('event:t:e2', { holder: 'new' })).toBe(true)
+    expect(store.get('event:t:e2').holder).toBe('new')
+  })
+})

package/src/tasks/in-process-sdk.js

@@ -1,35 +1,100 @@
 import { resolveActionId } from '@ossy/sdk'
+import { Aggregate } from '@ossy/event-store'
+import { User } from '@ossy/users/server'
+import { PoliciesQueries } from '@ossy/policies/server'
 import { ActionService } from '../actions/action.service.js'
 import { IntegrationService } from '../integration.service.js'
+import { ConfigService } from '../config.service.js'
 
 /**
- * Resolve actor/workspace from an eventstore document for nested action invokes.
+ * Bot request scoped to zero or more workspaces. Resource ACL treats this as a
+ * normal user actor (no system bypass).
  *
- * @param {object} [event]
- * @returns {{ userId: string, workspaceId?: string }}
+ * @param {{ workspaceId?: string, workspaces?: string[], policies?: unknown[] }} [options]
+ * @returns {{ userId: string, workspaceId?: string, user: object }}
  */
-function reqFromEvent (event) {
+export function botReq (options = {}) {
+  const userId = ConfigService.BotUserId
+  const workspaces = options.workspaceId
+    ? [options.workspaceId]
+    : (options.workspaces ?? [])
   return {
-    userId: event?.createdBy
-      ?? event?.payload?.createdBy
-      ?? event?.payload?.userId
-      ?? 'system',
-    workspaceId: event?.payload?.belongsTo
-      ?? event?.belongsTo
-      ?? event?.payload?.workspaceId,
+    userId,
+    ...(options.workspaceId ? { workspaceId: options.workspaceId } : {}),
+    user: {
+      id: userId,
+      workspaces,
+      policies: options.policies ?? [],
+    },
   }
 }
 
+/**
+ * Load the platform bot with live workspace membership and policies.
+ * Used when a task has no single workspace scope (global schedules).
+ *
+ * @returns {Promise<{ userId: string, user: object }>}
+ */
+export async function resolveBotReq () {
+  const userId = ConfigService.BotUserId
+  try {
+    const user = await Aggregate.Of(User, userId).then(Aggregate.View())
+    const policies = await PoliciesQueries.GetPoliciesForUser(userId).catch(() => [])
+    return {
+      userId,
+      user: {
+        ...user,
+        id: userId,
+        workspaces: user?.workspaces ?? [],
+        policies: policies ?? [],
+      },
+    }
+  } catch {
+    return botReq()
+  }
+}
+
+/**
+ * Bind the bot to the workspace on an eventstore document for nested invokes.
+ * Tasks run as the bot member, not as a system actor and not as the event author
+ * (an author userId without `req.user` would otherwise fold as anonymous).
+ *
+ * @param {object} [event]
+ * @returns {{ userId: string, workspaceId?: string, user: object }}
+ */
+function reqFromEvent (event) {
+  const workspaceId = event?.payload?.belongsTo
+    ?? event?.belongsTo
+    ?? event?.payload?.workspaceId
+  return botReq({ workspaceId })
+}
+
+/**
+ * Resolve the request bound to an in-process SDK instance.
+ * Explicit `req.user` wins. Workspace-scoped reqs get a bot membership stub.
+ * Otherwise load the bot's live workspaces.
+ *
+ * @param {{ userId?: string, workspaceId?: string, user?: object } | undefined} optionsReq
+ */
+function resolveReq (optionsReq) {
+  if (optionsReq?.user) return Promise.resolve(optionsReq)
+  if (optionsReq?.workspaceId) return Promise.resolve(botReq({ workspaceId: optionsReq.workspaceId }))
+  return resolveBotReq()
+}
+
 /**
  * Same-process SDK for changestream / scheduled tasks when no HTTP bot
  * credentials (`API_URL` + `OSSY_API_KEY`) are configured.
  *
+ * Actor is the platform bot (`ConfigService.BotUserId`) with workspace
+ * membership so resource ACL applies — not `userId: 'system'` (ACL bypass).
+ *
  * Implements `invoke` via ActionService (task outputs write through patch-content).
  *
- * @param {{ req?: { userId?: string, workspaceId?: string } }} [options]
+ * @param {{ req?: { userId?: string, workspaceId?: string, user?: object } }} [options]
  */
 export function createInProcessSdk (options = {}) {
-  const req = options.req ?? { userId: 'system' }
+  const optionsReq = options.req
 
   const sdk = {
     /**
@@ -38,21 +103,35 @@ export function createInProcessSdk (options = {}) {
      */
     invoke (action, payload = {}) {
       const actionId = resolveActionId(action)
-      return ActionService.invoke(actionId, {
+      return resolveReq(optionsReq).then((req) => ActionService.invoke(actionId, {
         payload,
         sdk,
         integrations: IntegrationService,
         req,
-      })
+      }))
     },
 
     /**
-     * Bind actor/workspace from a triggering event for one dispatch.
+     * Bind bot actor + workspace from a triggering event for one dispatch.
      * @param {object} event
      */
     withEventContext (event) {
       return createInProcessSdk({ req: reqFromEvent(event) })
     },
+
+    /**
+     * Bot limited to one workspace. Public and token entry points use this
+     * after they have resolved the workspace, so a visitor is not the actor
+     * and the bot cannot see other workspaces.
+     *
+     * @param {string} workspaceId
+     */
+    forWorkspace (workspaceId) {
+      if (!workspaceId) {
+        throw Object.assign(new Error('workspaceId is required'), { status: 400 })
+      }
+      return createInProcessSdk({ req: botReq({ workspaceId }) })
+    },
   }
 
   return sdk

package/src/tasks/in-process-sdk.spec.js

@@ -12,13 +12,59 @@ jest.unstable_mockModule('../integration.service.js', () => ({
   IntegrationService: { get: () => null },
 }))
 
-const { createInProcessSdk } = await import('./in-process-sdk.js')
+const botUserId = 'bot-user-id'
+jest.unstable_mockModule('../config.service.js', () => ({
+  ConfigService: { BotUserId: botUserId },
+}))
+
+jest.unstable_mockModule('@ossy/sdk', () => ({
+  resolveActionId: (action) => (typeof action === 'string' ? action : action.id),
+}), { virtual: true })
+
+jest.unstable_mockModule('@ossy/event-store', () => ({
+  Aggregate: {
+    Of: jest.fn(async () => ({})),
+    View: () => async () => ({ id: botUserId, workspaces: ['ws-bot'] }),
+  },
+}), { virtual: true })
+
+jest.unstable_mockModule('@ossy/users/server', () => ({
+  User: {},
+}), { virtual: true })
+
+jest.unstable_mockModule('@ossy/policies/server', () => ({
+  PoliciesQueries: {
+    GetPoliciesForUser: jest.fn(async () => []),
+  },
+}), { virtual: true })
+
+const { createInProcessSdk, botReq } = await import('./in-process-sdk.js')
 
 describe('createInProcessSdk', () => {
+  it('loads the bot with membership when no req is bound', async () => {
+    invokeMock.mockClear()
+    const sdk = createInProcessSdk()
+
+    await sdk.invoke({ id: '@ossy/resources/actions/get' }, { resourceId: 'r0' })
+
+    expect(invokeMock).toHaveBeenCalledWith(
+      '@ossy/resources/actions/get',
+      expect.objectContaining({
+        req: expect.objectContaining({
+          userId: botUserId,
+          user: expect.objectContaining({
+            id: botUserId,
+            workspaces: ['ws-bot'],
+          }),
+        }),
+      }),
+    )
+  })
+
   it('invokes actions in-process with bound req', async () => {
     invokeMock.mockClear()
     const sdk = createInProcessSdk({
-      req: { userId: 'u1', workspaceId: 'ws1' },
+      req: { userId: 'u1', workspaceId: 'ws1', user: { id: 'u1', workspaces: ['ws1'], policies: [] } },
     })
 
     await sdk.invoke({ id: '@ossy/resources/actions/get' }, { resourceId: 'r1' })
@@ -27,12 +73,12 @@ describe('createInProcessSdk', () => {
       '@ossy/resources/actions/get',
       expect.objectContaining({
         payload: { resourceId: 'r1' },
-        req: { userId: 'u1', workspaceId: 'ws1' },
+        req: expect.objectContaining({ userId: 'u1', workspaceId: 'ws1' }),
       }),
     )
   })
 
-  it('binds event actor/workspace via withEventContext', async () => {
+  it('binds the bot actor and workspace via withEventContext', async () => {
     invokeMock.mockClear()
     const sdk = createInProcessSdk().withEventContext({
       createdBy: 'author',
@@ -44,7 +90,39 @@ describe('createInProcessSdk', () => {
     expect(invokeMock).toHaveBeenCalledWith(
       '@ossy/resources/actions/get',
       expect.objectContaining({
-        req: { userId: 'author', workspaceId: 'workspace-a' },
+        req: botReq({ workspaceId: 'workspace-a' }),
+      }),
+    )
+  })
+
+  it('forWorkspace binds the bot to that workspace only', async () => {
+    invokeMock.mockClear()
+    const sdk = createInProcessSdk({
+      req: { userId: 'visitor', user: { id: 'visitor', anonymous: true, workspaces: [] } },
+    })
+
+    await sdk.forWorkspace('ws-public').invoke('@ossy/resources/actions/create', { workspaceId: 'ws-public' })
+
+    expect(invokeMock).toHaveBeenCalledWith(
+      '@ossy/resources/actions/create',
+      expect.objectContaining({
+        req: botReq({ workspaceId: 'ws-public' }),
+      }),
+    )
+  })
+
+  it('scopes the bot to the event workspace when the event has no actor', async () => {
+    invokeMock.mockClear()
+    const sdk = createInProcessSdk().withEventContext({
+      payload: { belongsTo: 'workspace-b' },
+    })
+
+    await sdk.invoke('@ossy/resources/actions/get', { resourceId: 'r3' })
+
+    expect(invokeMock).toHaveBeenCalledWith(
+      '@ossy/resources/actions/get',
+      expect.objectContaining({
+        req: botReq({ workspaceId: 'workspace-b' }),
       }),
     )
   })

package/src/tasks/task-service.js

@@ -1,6 +1,13 @@
 import { matchesGlob } from './glob.js'
 import { matchesCron } from './cron.js'
+import {
+  buildActionClaimKey,
+  buildEventClaimKey,
+  buildScheduleClaimKey,
+  tryClaimDispatch,
+} from './dispatch-claim.js'
 import { IntegrationService } from '../integration.service.js'
+import { ConfigService } from '../config.service.js'
 import { createLogger } from '@ossy/observability'
 import { isPrimaryTaskForAction, resolveTaskInputs, taskIdFromActionId } from '@ossy/schema'
 import { TaskRunService } from '../audit/task-run-service.js'
@@ -17,6 +24,42 @@ function buildTaskContext (baseContext, extras = {}) {
   }
 }
 
+/**
+ * In-process SDK bound to this request. Dynamic import avoids a cycle through
+ * ActionService. A missing req loads the bot; callers that have a user or a
+ * workspace-scoped bot req pass that through.
+ *
+ * @param {object | undefined} req
+ */
+async function sdkBoundTo (req) {
+  const { createInProcessSdk } = await import('./in-process-sdk.js')
+  return createInProcessSdk(req ? { req } : {})
+}
+
+async function botWorkspaceIds () {
+  const { resolveBotReq } = await import('./in-process-sdk.js')
+  const bot = await resolveBotReq()
+  const workspaces = bot?.user?.workspaces
+  if (!Array.isArray(workspaces)) return []
+  return [...new Set(workspaces.filter((id) => typeof id === 'string' && id))]
+}
+
+/**
+ * One cron firing per workspace. A global schedule must not run as a bot that
+ * can read every workspace in a single invoke.
+ *
+ * @param {string} schedule
+ * @param {string[]} workspaceIds
+ * @returns {Array<{ workspaceId: string, schedule: string }>}
+ */
+export function jobsForGlobalSchedule (schedule, workspaceIds) {
+  const trimmed = typeof schedule === 'string' ? schedule.trim() : ''
+  if (!trimmed) return []
+  return (workspaceIds ?? [])
+    .filter((id) => typeof id === 'string' && id)
+    .map((workspaceId) => ({ workspaceId, schedule: trimmed }))
+}
+
 export class TaskService {
 
   static _stopped = false
@@ -104,7 +147,9 @@ export class TaskService {
       ?? context?.event?.payload?.belongsTo
       ?? null
     let config = {}
-    if (TaskService._instanceConfigResolver && metadata?.id && workspaceId) {
+    // Only configurable tasks have instance config. Resolvers list resources by
+    // calling a task handler; resolving config for that list re-enters this path.
+    if (TaskService._instanceConfigResolver && metadata?.id && workspaceId && TaskService._isConfigurable(metadata)) {
       try {
         const loaded = await TaskService._instanceConfigResolver({
           taskId: metadata.id,
@@ -260,9 +305,11 @@ export class TaskService {
 
     // GET/API handlers often omit integrations; default like dispatch/scheduler so
     // tasks can always use integrations.get('email') (including local delivery).
+    // Nested invokes keep this sdk, so the first actor (the caller, or an sdk
+    // the entry point already bound) is the actor for the whole chain.
     const invokeContext = {
       ...context,
-      sdk: context.sdk ?? TaskService._sdk,
+      sdk: context.sdk ?? await sdkBoundTo(context.req),
       integrations: context.integrations ?? IntegrationService,
       log: context.log ?? createLogger(id),
     }
@@ -310,7 +357,7 @@ export class TaskService {
   static async dispatch(event, { sdk } = {}) {
     if (!event) return
 
-    const baseSdk = sdk ?? TaskService._sdk
+    const baseSdk = sdk ?? await sdkBoundTo()
     const effectiveSdk = typeof baseSdk?.withEventContext === 'function'
       ? baseSdk.withEventContext(event)
       : baseSdk
@@ -324,32 +371,43 @@ export class TaskService {
       const matchedTrigger = triggers.find((trigger) => TaskService._matchesEventTrigger(trigger, event))
       if (!matchedTrigger) continue
 
-      _serviceLog.info(`Dispatching task "${metadata.id}"`)
+      const _taskId = metadata.id
+      const claimKey = buildEventClaimKey(_taskId, event.id)
+
+      // Multiple startServer processes share Mongo changestreams (#982) — claim before run.
+      void (async () => {
+        const won = await tryClaimDispatch(claimKey)
+        if (!won) {
+          _serviceLog.info(`Skipping task "${_taskId}" — dispatch claim lost`)
+          return
+        }
 
-      const taskContext = buildTaskContext(
-        { sdk: effectiveSdk, integrations: IntegrationService, log: createLogger(metadata.id) },
-        {
-          event,
-          payload: { workspaceId },
-          triggerConfig: matchedTrigger.config,
-        },
-      )
+        _serviceLog.info(`Dispatching task "${_taskId}"`)
 
-      const _taskId = metadata.id
-      TaskRunService.executeAsync({
-        taskId: _taskId,
-        handler: TaskService._handlerWithInputs(metadata, handler),
-        context: taskContext,
-        trigger: 'on_event',
-        triggeredBy: {
-          eventId: event.id,
-          resourceId: event.resourceId,
-          type: event.type,
-          event: event.event,
-        },
-        executionEnv: 'ossy_server',
-        audit: metadata.audit !== false,
-      })
+        const taskContext = buildTaskContext(
+          { sdk: effectiveSdk, integrations: IntegrationService, log: createLogger(_taskId) },
+          {
+            event,
+            payload: { workspaceId },
+            triggerConfig: matchedTrigger.config,
+          },
+        )
+
+        TaskRunService.executeAsync({
+          taskId: _taskId,
+          handler: TaskService._handlerWithInputs(metadata, handler),
+          context: taskContext,
+          trigger: 'on_event',
+          triggeredBy: {
+            eventId: event.id,
+            resourceId: event.resourceId,
+            type: event.type,
+            event: event.event,
+          },
+          executionEnv: 'ossy_server',
+          audit: metadata.audit !== false,
+        })
+      })()
     }
   }
 
@@ -393,42 +451,52 @@ export class TaskService {
 
       if (!matchedTrigger) continue
 
-      _serviceLog.info(`Dispatching on_action task "${metadata.id}" for action "${actionId}"`)
-
-      const taskContext = buildTaskContext(
-        {
-          sdk: sdk ?? TaskService._sdk,
-          integrations: IntegrationService,
-          log: createLogger(metadata.id),
-          req,
-          actionInvocationId,
-          payload,
-          triggerConfig: matchedTrigger.config,
-        },
-        {
-          action: {
-            id: actionId,
-            success,
-            result,
-            error: error ? { message: error.message } : undefined,
+      const _taskId = metadata.id
+      const claimKey = buildActionClaimKey(_taskId, actionInvocationId)
+
+      void (async () => {
+        const won = await tryClaimDispatch(claimKey)
+        if (!won) {
+          _serviceLog.info(`Skipping on_action task "${_taskId}" — dispatch claim lost`)
+          return
+        }
+
+        _serviceLog.info(`Dispatching on_action task "${_taskId}" for action "${actionId}"`)
+
+        const taskContext = buildTaskContext(
+          {
+            sdk: sdk ?? await sdkBoundTo(req),
+            integrations: IntegrationService,
+            log: createLogger(_taskId),
+            req,
+            actionInvocationId,
+            payload,
+            triggerConfig: matchedTrigger.config,
           },
-        },
-      )
+          {
+            action: {
+              id: actionId,
+              success,
+              result,
+              error: error ? { message: error.message } : undefined,
+            },
+          },
+        )
 
-      const _taskId = metadata.id
-      TaskRunService.executeAsync({
-        taskId: _taskId,
-        handler: TaskService._handlerWithInputs(metadata, handler),
-        context: taskContext,
-        trigger: 'on_action',
-        triggeredBy: {
-          actionId,
-          actionInvocationId: actionInvocationId ?? null,
-          success,
-        },
-        executionEnv: 'ossy_server',
-        audit: metadata.audit !== false,
-      })
+        TaskRunService.executeAsync({
+          taskId: _taskId,
+          handler: TaskService._handlerWithInputs(metadata, handler),
+          context: taskContext,
+          trigger: 'on_action',
+          triggeredBy: {
+            actionId,
+            actionInvocationId: actionInvocationId ?? null,
+            success,
+          },
+          executionEnv: 'ossy_server',
+          audit: metadata.audit !== false,
+        })
+      })()
     }
   }
 
@@ -465,14 +533,15 @@ export class TaskService {
       return jobs
     }
 
+    const workspaceIds = await botWorkspaceIds()
     if (typeof metadata?.schedule === 'string' && metadata.schedule.trim()) {
-      jobs.push({ workspaceId: null, schedule: metadata.schedule.trim() })
+      jobs.push(...jobsForGlobalSchedule(metadata.schedule, workspaceIds))
     }
     for (const trigger of metadata?.triggers ?? []) {
       const kind = trigger?.trigger ?? trigger?.on ?? trigger?.kind
       const schedule = typeof trigger?.schedule === 'string' ? trigger.schedule.trim() : ''
       if ((kind === 'on_schedule' || (!kind && schedule)) && schedule) {
-        jobs.push({ workspaceId: null, schedule })
+        jobs.push(...jobsForGlobalSchedule(schedule, workspaceIds))
       }
     }
     return jobs
@@ -495,38 +564,61 @@ export class TaskService {
       const now = new Date()
 
       for (const { metadata, handler } of TaskService._tasks) {
-        TaskService._scheduledJobsFor(metadata).then((jobs) => {
+        TaskService._scheduledJobsFor(metadata).then(async (jobs) => {
           if (TaskService._stopped) return
           for (const job of jobs) {
+            if (!job.workspaceId) continue
             if (!matchesCron(job.schedule, now)) continue
 
-            _serviceLog.info(
-              `Schedule fired for task "${metadata.id}"`
-              + (job.workspaceId ? ` (workspace ${job.workspaceId})` : ''),
-            )
-
-            const taskContext = {
-              event: { type: 'scheduled', taskId: metadata.id },
-              sdk: TaskService._sdk,
-              integrations: IntegrationService,
-              log: createLogger(metadata.id),
-              payload: job.workspaceId ? { workspaceId: job.workspaceId } : undefined,
-              req: job.workspaceId ? { workspaceId: job.workspaceId, userId: 'system' } : undefined,
-              triggerConfig: job.config,
-            }
-
-            TaskRunService.executeAsync({
-              taskId: metadata.id,
-              handler: TaskService._handlerWithInputs(metadata, handler),
-              context: taskContext,
-              trigger: 'on_schedule',
-              triggeredBy: {
-                schedule: job.schedule,
-                ...(job.workspaceId ? { workspaceId: job.workspaceId } : {}),
-              },
-              executionEnv: 'ossy_server',
-              audit: metadata.audit !== false,
-            })
+            const claimKey = buildScheduleClaimKey(metadata.id, job.workspaceId, now)
+            void (async () => {
+              const won = await tryClaimDispatch(claimKey)
+              if (!won) {
+                _serviceLog.info(
+                  `Skipping schedule for task "${metadata.id}" — dispatch claim lost`
+                  + (job.workspaceId ? ` (workspace ${job.workspaceId})` : ''),
+                )
+                return
+              }
+
+              _serviceLog.info(
+                `Schedule fired for task "${metadata.id}"`
+                + (job.workspaceId ? ` (workspace ${job.workspaceId})` : ''),
+              )
+
+              const req = {
+                userId: ConfigService.BotUserId,
+                workspaceId: job.workspaceId,
+                user: {
+                  id: ConfigService.BotUserId,
+                  workspaces: [job.workspaceId],
+                  policies: [],
+                },
+              }
+              const taskContext = {
+                event: { type: 'scheduled', taskId: metadata.id },
+                sdk: await sdkBoundTo(req),
+                integrations: IntegrationService,
+                log: createLogger(metadata.id),
+                payload: job.workspaceId ? { workspaceId: job.workspaceId } : undefined,
+                // Bot member of this workspace only. Nested sdk.invoke keeps this req.
+                req,
+                triggerConfig: job.config,
+              }
+
+              TaskRunService.executeAsync({
+                taskId: metadata.id,
+                handler: TaskService._handlerWithInputs(metadata, handler),
+                context: taskContext,
+                trigger: 'on_schedule',
+                triggeredBy: {
+                  schedule: job.schedule,
+                  ...(job.workspaceId ? { workspaceId: job.workspaceId } : {}),
+                },
+                executionEnv: 'ossy_server',
+                audit: metadata.audit !== false,
+              })
+            })()
           }
         }).catch((err) => {
           _serviceLog.warn(

package/src/tasks/task-service.spec.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from '@jest/globals'
-import { TaskService } from './task-service.js'
+import { jobsForGlobalSchedule, TaskService } from './task-service.js'
 import { TaskRun } from '../audit/task-run.aggregate.js'
 import { ActionInvocation } from '../audit/action-invocation.aggregate.js'
 import { TaskRunListProjection } from '../audit/task-run-list.aggregate.js'
@@ -7,6 +7,19 @@ import { detectChannel } from '../audit/detect-channel.js'
 import { hashPayload, moduleIdFromTaskId } from '../audit/audit-helpers.js'
 import { isPrimaryTaskForAction, taskIdFromActionId } from '@ossy/schema'
 
+describe('jobsForGlobalSchedule', () => {
+  it('fires once per workspace', () => {
+    expect(jobsForGlobalSchedule('0 * * * *', ['ws-a', 'ws-b'])).toEqual([
+      { workspaceId: 'ws-a', schedule: '0 * * * *' },
+      { workspaceId: 'ws-b', schedule: '0 * * * *' },
+    ])
+  })
+
+  it('returns no jobs when the bot has no workspaces', () => {
+    expect(jobsForGlobalSchedule('0 6 * * *', [])).toEqual([])
+  })
+})
+
 describe('TaskService triggers', () => {
   it('matches on_action triggers with glob patterns', () => {
     expect(TaskService._matchesActionTrigger(