@ossy/platform 3.8.0 → 3.11.0

package/README.md

@@ -60,6 +60,8 @@ Optional environment variables used by the platform itself:
 | Variable | Description |
 |---|---|
 | `DB_URL` | MongoDB connection string. Required for tasks and aggregates. |
+| `MONGO_MAX_POOL_SIZE` | Per-process MongoDB driver pool size (default `50`). Each ECS task shares one client for the event store and change stream — raise only if you see wait-queue latency. |
+| `MONGO_MAX_IDLE_TIME_MS` | Optional. When set to a positive ms value, closes idle pool sockets after that idle time. Unset by default (no idle churn). |
 | `API_URL` + `OSSY_API_KEY` | Optional HTTP bot SDK for tasks. When unset, tasks get an in-process SDK that calls `ActionService` / storage in the same process (local app-test and same-server changestream). |
 | `PORT` | HTTP port. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/platform",
-  "version": "3.8.0",
+  "version": "3.11.0",
   "description": "Ossy application server runtime",
   "repository": {
     "type": "git",
@@ -45,16 +45,16 @@
     "@aws-sdk/util-format-url": "^3.972.17",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@ossy/config": "^3.0.9",
-    "@ossy/event-store": "^3.8.0",
+    "@ossy/event-store": "^3.11.0",
     "@ossy/locale": "^3.4.0",
-    "@ossy/manifest": "^3.8.0",
+    "@ossy/manifest": "^3.9.0",
     "@ossy/observability": "^3.0.9",
     "@ossy/policies": "^3.0.9",
     "@ossy/schema": "^3.8.0",
     "@ossy/sdk": "^3.5.0",
     "@ossy/tokens": "^3.5.0",
-    "@ossy/users": "^3.8.0",
-    "@ossy/workspaces": "^3.8.0",
+    "@ossy/users": "^3.11.0",
+    "@ossy/workspaces": "^3.11.0",
     "cookie-parser": "^1.4.7",
     "dotenv": ">=16.0.0 <18.0.0",
     "express": ">=5.0.0 <6.0.0",
@@ -75,5 +75,5 @@
     "Dockerfile",
     "docker-healthcheck.js"
   ],
-  "gitHead": "14548dfc2019e7258e8c75db527acbf66fe829bd"
+  "gitHead": "53ff8456920e09151c9d88df4a6c3ee958d811eb"
 }

package/src/index.js

@@ -15,8 +15,10 @@ export { matchesCron } from './tasks/cron.js'
 export { matchesGlob, globToRegex, policyToQueryClause } from './tasks/glob.js'
 export {
   USER_SETTINGS_COOKIE,
+  WORKSPACE_ID_COOKIE,
   AUTH_COOKIE,
   readUserAppSettings,
+  readWorkspaceIdFromCookies,
   mergeUserAppSettingsCookie,
   clearWorkspaceFromUserAppSettings,
   setAuthCookie,

package/src/proxy-internal.js

@@ -2,6 +2,7 @@ import { createLogger } from '@ossy/observability'
 import {
   mergeUserAppSettingsCookie,
   readUserAppSettings,
+  readWorkspaceIdFromCookies,
 } from './user-app-settings.js'
 
 const log = createLogger('platform')
@@ -26,7 +27,10 @@ export function ProxyInternal () {
         return
       }
 
-      const requestedSettings = req.body
+      const requestedSettings = { ...req.body }
+      // Active workspace is selected via /users/select-workspace (and sign-in).
+      // Shell Sync must not send workspaceId — strip if a client does.
+      delete requestedSettings.workspaceId
       mergeUserAppSettingsCookie(req, res, requestedSettings)
 
       res.status(201)
@@ -37,8 +41,9 @@ export function ProxyInternal () {
     if (req.originalUrl.startsWith('/@ossy/users/me/app-settings') && req.method === 'GET') {
       log.info('[@ossy/platform][proxy] GET /@ossy/users/me/app-settings')
       const userSettings = readUserAppSettings(req)
+      const workspaceId = readWorkspaceIdFromCookies(req)
       res.status(200)
-      res.json(userSettings)
+      res.json(workspaceId ? { ...userSettings, workspaceId } : userSettings)
       return
     }
 

package/src/runtime.js

@@ -11,6 +11,7 @@ import { ProxyInternal } from './proxy-internal.js'
 import { loadSite, invalidateSite } from './site-loader.js'
 import { createLogger } from '@ossy/observability'
 import { mountHealthEndpoint } from './health.js'
+import { readWorkspaceIdFromCookies } from './user-app-settings.js'
 
 const log = createLogger('platform')
 
@@ -86,9 +87,10 @@ export async function startRuntime ({ port } = {}) {
 
   app.use((req, _res, next) => {
     const userSettings = JSON.parse(req.signedCookies?.['x-ossy-user-settings'] || '{}')
-    req.userAppSettings = userSettings
-    if (userSettings.workspaceId && !req.get('workspaceId')) {
-      req.headers.workspaceid = userSettings.workspaceId
+    const workspaceId = readWorkspaceIdFromCookies(req) || userSettings.workspaceId
+    req.userAppSettings = workspaceId ? { ...userSettings, workspaceId } : userSettings
+    if (workspaceId && !req.get('workspaceId')) {
+      req.headers.workspaceid = workspaceId
     }
     // Prefer a verified signed auth cookie; fall back to presence only when unsigned.
     req.isAuthenticated = !!(req.signedCookies?.auth)

package/src/select-workspace.api.js

@@ -35,7 +35,11 @@ export default async function handle (req, res) {
       return
     }
 
-    mergeUserAppSettingsCookie(req, res, { workspaceId })
+    const selected = workspaces.find((w) => w.id === workspaceId)
+    mergeUserAppSettingsCookie(req, res, {
+      workspaceId,
+      ...(selected?.name ? { workspaceName: selected.name } : {}),
+    })
 
     const redirect = req.query.redirect
     if (redirect && typeof redirect === 'string') {

package/src/server.js

@@ -43,6 +43,7 @@ import {
 import {
   clearAuthCookie,
   clearWorkspaceFromUserAppSettings,
+  readWorkspaceIdFromCookies,
 } from './user-app-settings.js'
 const log = createLogger('@ossy/platform')
 const MONGO_TIMEOUT_MS = resolveTimeoutMs('OSSY_MONGO_TIMEOUT_MS', 10_000)
@@ -330,9 +331,10 @@ export async function startServer (options = {}) {
   app.use(cookieParser(ConfigService.TokenSecret))
   app.use((req, _res, next) => {
     const userSettings = JSON.parse(req.signedCookies?.['x-ossy-user-settings'] || '{}')
-    req.userAppSettings = userSettings
-    if (userSettings.workspaceId && !req.get('workspaceId')) {
-      req.headers.workspaceid = userSettings.workspaceId
+    const workspaceId = readWorkspaceIdFromCookies(req) || userSettings.workspaceId
+    req.userAppSettings = workspaceId ? { ...userSettings, workspaceId } : userSettings
+    if (workspaceId && !req.get('workspaceId')) {
+      req.headers.workspaceid = workspaceId
     }
     next()
   })
@@ -679,8 +681,10 @@ export { getPlatformSchema, initPlatformSchema, createSchemaEngine, schemaForWor
 export { validateSchemasForImport } from './resources/schema.validation.js'
 export {
   USER_SETTINGS_COOKIE,
+  WORKSPACE_ID_COOKIE,
   AUTH_COOKIE,
   readUserAppSettings,
+  readWorkspaceIdFromCookies,
   mergeUserAppSettingsCookie,
   clearWorkspaceFromUserAppSettings,
   setAuthCookie,

package/src/tasks/change-stream.js

@@ -1,6 +1,6 @@
 import { TaskService } from './task-service.js'
 import { createLogger } from '@ossy/observability'
-import { ProjectionRebuild, PushInvalidation, resolveMongoUrl } from '@ossy/event-store'
+import { Mongo, ProjectionRebuild, PushInvalidation } from '@ossy/event-store'
 
 const log = createLogger('platform')
 
@@ -11,26 +11,20 @@ function isMongoTopologyClosedError(error) {
   return false
 }
 
+/** Watches `eventstore` inserts. Uses the shared {@link Mongo} client — one per process. */
 export class ChangeStream {
 
   static _stopped = false
   static _reconnectAttempts = 0
-  static _dbUrl = null
-  static _client = null
   /** @type {import('mongodb').ChangeStream | null} */
   static _changeStream = null
   /** @type {ReturnType<typeof setTimeout> | null} */
   static _reconnectTimer = null
 
-  /**
-   * Opens the MongoDB changestream and wires up reconnect logic.
-   * Logs errors; does not crash the process on Mongo outages.
-   * @param {string} dbUrl - MongoDB connection URL (process.env.DB_URL)
-   */
-  static start(dbUrl) {
+  /** @param {string} [_dbUrl] - Unused; kept for call-site compatibility. */
+  static start(_dbUrl) {
     ChangeStream._stopped = false
     ChangeStream._reconnectAttempts = 0
-    ChangeStream._dbUrl = resolveMongoUrl(dbUrl)
     ChangeStream._open().catch((error) => {
       log.error('[ChangeStream] Change stream could not be opened', undefined, error)
       ChangeStream._scheduleReconnect()
@@ -55,48 +49,20 @@ export class ChangeStream {
       }
     }
 
-    const client = ChangeStream._client
-    ChangeStream._client = null
-    if (client) {
-      try {
-        await client.close()
-      } catch {
-        // ignore
-      }
-    }
-
     log.info('[ChangeStream] Stopped')
   }
 
-  static async _getMongoClient() {
-    const { MongoClient } = await import('mongodb')
-    return MongoClient
-  }
-
-  static async _getClient () {
+  static _getClient () {
     if (ChangeStream._stopped) {
       throw new Error('ChangeStream stopped')
     }
-    if (!ChangeStream._client) {
-      const MongoClient = await ChangeStream._getMongoClient()
-      ChangeStream._client = new MongoClient(ChangeStream._dbUrl, {
-        serverSelectionTimeoutMS: 30_000,
-      })
-    }
-    return ChangeStream._client
+    return Mongo.Client
   }
 
-  static async _resetClient () {
+  static _resetSharedClient () {
     if (ChangeStream._stopped) return
-    const MongoClient = await ChangeStream._getMongoClient()
-    const prev = ChangeStream._client
-    ChangeStream._client = new MongoClient(ChangeStream._dbUrl, {
-      serverSelectionTimeoutMS: 30_000,
-    })
-    if (prev) {
-      prev.close().catch(() => {})
-    }
-    log.info('[ChangeStream] New MongoClient instance created')
+    Mongo.resetClient()
+    log.info('[ChangeStream] Shared Mongo client reset')
   }
 
   static _scheduleReconnect () {
@@ -127,7 +93,7 @@ export class ChangeStream {
     log.info('[ChangeStream] Watching for changes')
 
     const dbName = process.env.DB_NAME || 'test'
-    const client = await ChangeStream._getClient()
+    const client = ChangeStream._getClient()
     if (ChangeStream._stopped) return
 
     const collection = client.db(dbName).collection('eventstore')
@@ -166,7 +132,7 @@ export class ChangeStream {
       if (ChangeStream._stopped) return
       log.error('[ChangeStream] Change stream error (server keeps running)', undefined, error)
       if (isMongoTopologyClosedError(error)) {
-        ChangeStream._resetClient().catch(() => {})
+        ChangeStream._resetSharedClient()
       }
       scheduleOnce()
     })

package/src/test/flow-action.js

@@ -0,0 +1,62 @@
+/**
+ * Shared helpers for resolving action POJOs in declarative flow steps.
+ */
+
+/**
+ * @param {unknown} action
+ * @returns {string}
+ */
+export function resolveActionId (action) {
+  if (typeof action === 'string') return action
+  if (action && typeof action.id === 'string') return action.id
+  throw new Error('Flow action step requires an action POJO or id string')
+}
+
+/**
+ * Optional discriminators for when multiple controls share an action id
+ * (e.g. per-row OpenRemoveMember beside a system bot row, or language switch targets).
+ *
+ * @param {unknown} action
+ * @param {{ service?: string, memberEmail?: string, language?: string }} [fallback]
+ * @returns {{ service?: string, memberEmail?: string, language?: string }}
+ */
+export function resolveActionMatchers (action, fallback = {}) {
+  const fromAction = typeof action === 'object' && action != null ? action : {}
+  const service = fromAction.service ?? fromAction['data-service'] ?? fallback.service
+  const memberEmail = fromAction.memberEmail
+    ?? fromAction['data-member-email']
+    ?? fallback.memberEmail
+  const language = fromAction.language
+    ?? fromAction['data-language']
+    ?? fallback.language
+  return {
+    ...(service != null && service !== '' ? { service: String(service) } : {}),
+    ...(memberEmail != null && memberEmail !== '' ? { memberEmail: String(memberEmail) } : {}),
+    ...(language != null && language !== '' ? { language: String(language) } : {}),
+  }
+}
+
+/**
+ * @param {string} actionId
+ * @param {string | { service?: string, memberEmail?: string, language?: string }} [serviceOrMatchers]
+ * @returns {string}
+ */
+export function actionSelector (actionId, serviceOrMatchers) {
+  const matchers = typeof serviceOrMatchers === 'string'
+    ? { service: serviceOrMatchers }
+    : (serviceOrMatchers ?? {})
+  let selector = `[data-action="${actionId}"]`
+  if (matchers.service) selector += `[data-service="${matchers.service}"]`
+  if (matchers.memberEmail) selector += `[data-member-email="${matchers.memberEmail}"]`
+  if (matchers.language) selector += `[data-language="${matchers.language}"]`
+  return selector
+}
+
+/**
+ * @param {unknown} action
+ * @param {string} [fallback]
+ * @returns {string | undefined}
+ */
+export function resolveActionService (action, fallback) {
+  return resolveActionMatchers(action, { service: fallback }).service
+}

package/src/test/flow-action.spec.js

@@ -0,0 +1,64 @@
+import { describe, expect, it } from '@jest/globals'
+import {
+  actionSelector,
+  resolveActionId,
+  resolveActionMatchers,
+  resolveActionService,
+} from './flow-action.js'
+
+describe('resolveActionId', () => {
+  it('reads id from a POJO', () => {
+    expect(resolveActionId({ id: '@ossy/app/actions/switch-language' }))
+      .toBe('@ossy/app/actions/switch-language')
+  })
+
+  it('accepts a bare id string', () => {
+    expect(resolveActionId('@ossy/app/actions/switch-language'))
+      .toBe('@ossy/app/actions/switch-language')
+  })
+})
+
+describe('resolveActionMatchers', () => {
+  it('reads service, memberEmail, and language from the action POJO', () => {
+    expect(resolveActionMatchers({
+      id: 'x',
+      service: 'booking',
+      memberEmail: 'a@b.c',
+      language: 'sv',
+    })).toEqual({
+      service: 'booking',
+      memberEmail: 'a@b.c',
+      language: 'sv',
+    })
+  })
+
+  it('falls back to data-* keys and step fallbacks', () => {
+    expect(resolveActionMatchers(
+      { 'data-service': 'timesheets', 'data-member-email': 'x@y.z', 'data-language': 'en' },
+      { service: 'ignored', memberEmail: 'ignored', language: 'ignored' },
+    )).toEqual({
+      service: 'timesheets',
+      memberEmail: 'x@y.z',
+      language: 'en',
+    })
+  })
+})
+
+describe('actionSelector', () => {
+  it('includes language in the selector', () => {
+    expect(actionSelector('@ossy/app/actions/switch-language', { language: 'sv' }))
+      .toBe('[data-action="@ossy/app/actions/switch-language"][data-language="sv"]')
+  })
+
+  it('still supports a bare service string', () => {
+    expect(actionSelector('@ossy/workspaces/actions/enable-service', 'booking'))
+      .toBe('[data-action="@ossy/workspaces/actions/enable-service"][data-service="booking"]')
+  })
+})
+
+describe('resolveActionService', () => {
+  it('delegates to matchers', () => {
+    expect(resolveActionService({ service: 'analytics' })).toBe('analytics')
+    expect(resolveActionService({}, 'booking')).toBe('booking')
+  })
+})

package/src/test/flow-context.js

@@ -42,3 +42,23 @@ export function interpolateContextString (template, context, options = {}) {
     return escape(value)
   })
 }
+
+/**
+ * Merge optional form-step field overrides into faker-mocked content.
+ * Values may be `$contextKey` placeholders (e.g. `{ email: '$email' }`).
+ *
+ * @param {Record<string, unknown>} content
+ * @param {Record<string, unknown> | null | undefined} overrides
+ * @param {{ fields?: Record<string, unknown>, [key: string]: unknown }} context
+ * @returns {Record<string, unknown>}
+ */
+export function applyFormFieldOverrides (content, overrides, context) {
+  if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)) {
+    return content
+  }
+  const next = { ...content }
+  for (const [name, raw] of Object.entries(overrides)) {
+    next[name] = resolveContextValue(raw, context)
+  }
+  return next
+}

package/src/test/flow-context.spec.js

@@ -1,5 +1,6 @@
 import { describe, expect, it } from '@jest/globals'
 import {
+  applyFormFieldOverrides,
   escapeCssAttrValue,
   interpolateContextString,
   resolveContextValue,
@@ -41,4 +42,17 @@ describe('flow-context', () => {
       interpolateContextString('[data-x="$missing"]', context),
     ).toBe('[data-x="$missing"]')
   })
+
+  it('applies form field overrides with $context placeholders', () => {
+    const mocked = { email: 'faker@example.com', firstName: 'Faker' }
+    expect(
+      applyFormFieldOverrides(mocked, { email: '$email' }, context),
+    ).toEqual({ email: 'new@example.com', firstName: 'Faker' })
+  })
+
+  it('returns content unchanged when overrides are missing', () => {
+    const mocked = { email: 'faker@example.com' }
+    expect(applyFormFieldOverrides(mocked, null, context)).toBe(mocked)
+    expect(applyFormFieldOverrides(mocked, undefined, context)).toBe(mocked)
+  })
 })

package/src/test/flow-download.js

@@ -0,0 +1,102 @@
+/**
+ * Resolve a declarative `{ download }` flow step.
+ *
+ * Clicks an action (or CSS selector) while waiting for one or more browser
+ * download events — used for single-file and batch download journeys.
+ */
+
+import { resolveActionId, resolveActionService } from './flow-action.js'
+
+/**
+ * @param {unknown} value
+ * @returns {{
+ *   actionId: string | null,
+ *   service: string | undefined,
+ *   selector: string | null,
+ *   count: number,
+ *   filenames: string[],
+ *   timeout: number,
+ * }}
+ */
+export function resolveDownloadTarget (value) {
+  if (value == null || (typeof value !== 'object' && typeof value !== 'string')) {
+    throw new Error('download step requires { action } or { selector }')
+  }
+
+  const spec = typeof value === 'string'
+    ? { action: value }
+    : value
+
+  const actionRaw = spec.action
+  const selectorRaw = typeof spec.selector === 'string' ? spec.selector.trim() : ''
+  let actionId = null
+  let service = typeof spec.service === 'string' ? spec.service : undefined
+
+  if (actionRaw != null) {
+    actionId = resolveActionId(actionRaw)
+    service = resolveActionService(actionRaw, service)
+  }
+
+  if (!actionId && !selectorRaw) {
+    throw new Error('download step requires { action } or a non-empty { selector }')
+  }
+
+  const filenames = []
+  if (spec.filename != null) {
+    if (typeof spec.filename !== 'string' || !spec.filename.trim()) {
+      throw new Error('download.filename must be a non-empty string')
+    }
+    filenames.push(spec.filename.trim())
+  }
+  if (Array.isArray(spec.filenames)) {
+    for (let i = 0; i < spec.filenames.length; i += 1) {
+      const name = spec.filenames[i]
+      if (typeof name !== 'string' || !name.trim()) {
+        throw new Error(`download.filenames[${i}] must be a non-empty string`)
+      }
+      filenames.push(name.trim())
+    }
+  } else if (spec.filenames != null) {
+    throw new Error('download.filenames must be an array of strings')
+  }
+
+  const countRaw = spec.count
+  const inferredCount = spec.count == null && filenames.length > 1 ? filenames.length : null
+  const count = inferredCount ?? (countRaw == null ? 1 : Number(countRaw))
+  if (!Number.isInteger(count) || count < 1) {
+    throw new Error('download.count must be a positive integer')
+  }
+
+  const timeoutRaw = spec.timeout
+  const timeout = timeoutRaw == null ? 30000 : Number(timeoutRaw)
+  if (!Number.isFinite(timeout) || timeout <= 0) {
+    throw new Error('download.timeout must be a positive number')
+  }
+
+  return {
+    actionId,
+    service,
+    selector: selectorRaw || null,
+    count,
+    filenames,
+    timeout,
+  }
+}
+
+/**
+ * @param {string[]} suggested
+ * @param {string[]} expected
+ */
+export function assertDownloadFilenames (suggested, expected) {
+  if (!expected.length) return
+  const remaining = [...suggested]
+  for (const name of expected) {
+    const index = remaining.indexOf(name)
+    if (index === -1) {
+      throw new Error(
+        `Expected download filename "${name}" not found in [${suggested.join(', ')}]`,
+      )
+    }
+    remaining.splice(index, 1)
+  }
+}

package/src/test/flow-download.spec.js

@@ -0,0 +1,60 @@
+import { describe, expect, it } from '@jest/globals'
+import {
+  assertDownloadFilenames,
+  resolveDownloadTarget,
+} from './flow-download.js'
+
+describe('resolveDownloadTarget', () => {
+  it('accepts an action POJO and optional filename', () => {
+    expect(resolveDownloadTarget({
+      action: { id: '@ossy/resources/actions/download-resource' },
+      filename: 'e2e-upload.txt',
+    })).toEqual({
+      actionId: '@ossy/resources/actions/download-resource',
+      service: undefined,
+      selector: null,
+      count: 1,
+      filenames: ['e2e-upload.txt'],
+      timeout: 30000,
+    })
+  })
+
+  it('infers count from filenames when count is omitted', () => {
+    expect(resolveDownloadTarget({
+      action: '@ossy/resources/actions/download-selected',
+      filenames: ['a.txt', 'b.txt'],
+    })).toMatchObject({
+      count: 2,
+      filenames: ['a.txt', 'b.txt'],
+    })
+  })
+
+  it('accepts a CSS selector fallback', () => {
+    expect(resolveDownloadTarget({
+      selector: ' [data-download] ',
+      count: 1,
+    })).toMatchObject({
+      actionId: null,
+      selector: '[data-download]',
+      count: 1,
+    })
+  })
+
+  it('rejects invalid values', () => {
+    expect(() => resolveDownloadTarget(null)).toThrow(/requires \{ action \}/)
+    expect(() => resolveDownloadTarget({})).toThrow(/requires \{ action \}/)
+    expect(() => resolveDownloadTarget({ action: 'x', count: 0 })).toThrow(/positive integer/)
+    expect(() => resolveDownloadTarget({ action: 'x', filename: '' })).toThrow(/filename/)
+    expect(() => resolveDownloadTarget({ action: 'x', timeout: -1 })).toThrow(/timeout/)
+  })
+})
+
+describe('assertDownloadFilenames', () => {
+  it('passes when expected names are present', () => {
+    expect(() => assertDownloadFilenames(['a.txt', 'b.txt'], ['b.txt', 'a.txt'])).not.toThrow()
+  })
+
+  it('fails when a name is missing', () => {
+    expect(() => assertDownloadFilenames(['a.txt'], ['b.txt'])).toThrow(/b\.txt/)
+  })
+})

package/src/test/flow-files.js

@@ -0,0 +1,83 @@
+/**
+ * Normalize a declarative flow `files` step into Playwright `setInputFiles` payloads.
+ * Use for native file inputs (`type=file`) — form fills intentionally skip file fields.
+ *
+ * @param {unknown} files
+ * @returns {{
+ *   selector: string,
+ *   payloads: Array<string | { name: string, mimeType: string, buffer: Buffer }>
+ * }}
+ */
+export function resolveFilesTarget (files) {
+  if (files == null || typeof files !== 'object' || Array.isArray(files)) {
+    throw new Error('files step requires { selector, paths? } or { selector, items? }')
+  }
+
+  const selector = typeof files.selector === 'string' ? files.selector.trim() : ''
+  if (!selector) {
+    throw new Error('files step requires a non-empty CSS selector')
+  }
+
+  const paths = normalizePathList(files.paths ?? files.path)
+  const items = normalizeItemList(files.items ?? files.item)
+
+  if (paths.length === 0 && items.length === 0) {
+    throw new Error('files step requires at least one path or item')
+  }
+
+  /** @type {Array<string | { name: string, mimeType: string, buffer: Buffer }>} */
+  const payloads = [
+    ...paths,
+    ...items.map((item) => ({
+      name: item.name,
+      mimeType: item.mimeType,
+      buffer: Buffer.from(item.content, item.encoding ?? 'utf8'),
+    })),
+  ]
+
+  return { selector, payloads }
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {string[]}
+ */
+function normalizePathList (raw) {
+  if (raw == null) return []
+  const list = Array.isArray(raw) ? raw : [raw]
+  return list.map((entry, index) => {
+    if (typeof entry !== 'string' || !entry.trim()) {
+      throw new Error(`files.paths[${index}] must be a non-empty string`)
+    }
+    return entry.trim()
+  })
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {Array<{ name: string, mimeType: string, content: string, encoding?: BufferEncoding }>}
+ */
+function normalizeItemList (raw) {
+  if (raw == null) return []
+  const list = Array.isArray(raw) ? raw : [raw]
+  return list.map((entry, index) => {
+    if (entry == null || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new Error(`files.items[${index}] must be an object`)
+    }
+    const name = typeof entry.name === 'string' ? entry.name.trim() : ''
+    if (!name) {
+      throw new Error(`files.items[${index}].name must be a non-empty string`)
+    }
+    if (typeof entry.content !== 'string') {
+      throw new Error(`files.items[${index}].content must be a string`)
+    }
+    const mimeType = typeof entry.mimeType === 'string' && entry.mimeType.trim()
+      ? entry.mimeType.trim()
+      : 'application/octet-stream'
+    const encoding = entry.encoding == null ? undefined : entry.encoding
+    if (encoding != null && typeof encoding !== 'string') {
+      throw new Error(`files.items[${index}].encoding must be a string when set`)
+    }
+    return { name, mimeType, content: entry.content, encoding }
+  })
+}

package/src/test/flow-files.spec.js

@@ -0,0 +1,69 @@
+import { describe, expect, it } from '@jest/globals'
+import { resolveFilesTarget } from './flow-files.js'
+
+describe('resolveFilesTarget', () => {
+  it('accepts a single filesystem path', () => {
+    expect(resolveFilesTarget({
+      selector: ' #upload-resources ',
+      path: ' /tmp/sample.txt ',
+    })).toEqual({
+      selector: '#upload-resources',
+      payloads: ['/tmp/sample.txt'],
+    })
+  })
+
+  it('accepts multiple filesystem paths', () => {
+    expect(resolveFilesTarget({
+      selector: '#upload-resources',
+      paths: ['a.txt', 'b.txt'],
+    })).toEqual({
+      selector: '#upload-resources',
+      payloads: ['a.txt', 'b.txt'],
+    })
+  })
+
+  it('accepts in-memory buffer items', () => {
+    const resolved = resolveFilesTarget({
+      selector: '#upload-resources',
+      items: [{
+        name: 'e2e-upload.txt',
+        mimeType: 'text/plain',
+        content: 'hello from e2e',
+      }],
+    })
+    expect(resolved.selector).toBe('#upload-resources')
+    expect(resolved.payloads).toHaveLength(1)
+    expect(resolved.payloads[0]).toMatchObject({
+      name: 'e2e-upload.txt',
+      mimeType: 'text/plain',
+    })
+    expect(Buffer.isBuffer(resolved.payloads[0].buffer)).toBe(true)
+    expect(resolved.payloads[0].buffer.toString('utf8')).toBe('hello from e2e')
+  })
+
+  it('defaults mimeType for buffer items', () => {
+    const resolved = resolveFilesTarget({
+      selector: '[data-ossy-upload-input]',
+      item: { name: 'blob.bin', content: 'x' },
+    })
+    expect(resolved.payloads[0].mimeType).toBe('application/octet-stream')
+  })
+
+  it('rejects empty or invalid values', () => {
+    expect(() => resolveFilesTarget(null)).toThrow(/requires \{ selector/)
+    expect(() => resolveFilesTarget({ selector: '' })).toThrow(/non-empty CSS selector/)
+    expect(() => resolveFilesTarget({ selector: '#x' })).toThrow(/at least one path or item/)
+    expect(() => resolveFilesTarget({
+      selector: '#x',
+      paths: [''],
+    })).toThrow(/files\.paths\[0\]/)
+    expect(() => resolveFilesTarget({
+      selector: '#x',
+      items: [{ name: '', content: 'x' }],
+    })).toThrow(/files\.items\[0\]\.name/)
+    expect(() => resolveFilesTarget({
+      selector: '#x',
+      items: [{ name: 'a.txt', content: 1 }],
+    })).toThrow(/files\.items\[0\]\.content/)
+  })
+})

package/src/test/flow-runner.js

@@ -15,20 +15,36 @@ import { Router } from '@ossy/router'
 import { Schema } from '@ossy/schema'
 import { test, expect } from '@playwright/test'
 import {
+  applyFormFieldOverrides,
   escapeCssAttrValue,
   interpolateContextString,
   resolveContextValue,
 } from './flow-context.js'
+import { actionSelector, resolveActionId, resolveActionMatchers, resolveActionService } from './flow-action.js'
 import { resolveClickTarget } from './flow-click.js'
+import { assertDownloadFilenames, resolveDownloadTarget } from './flow-download.js'
+import { resolveFilesTarget } from './flow-files.js'
 import { resolvePressKey } from './flow-press.js'
 import { resolveViewportSize } from './flow-viewport.js'
 
 export {
+  applyFormFieldOverrides,
   escapeCssAttrValue,
   interpolateContextString,
   resolveContextValue,
 } from './flow-context.js'
+export {
+  actionSelector,
+  resolveActionId,
+  resolveActionMatchers,
+  resolveActionService,
+} from './flow-action.js'
 export { resolveClickTarget } from './flow-click.js'
+export {
+  assertDownloadFilenames,
+  resolveDownloadTarget,
+} from './flow-download.js'
+export { resolveFilesTarget } from './flow-files.js'
 export { resolvePressKey } from './flow-press.js'
 export { resolveViewportSize } from './flow-viewport.js'
 
@@ -92,15 +108,20 @@ function schemaEngineFromManifest (manifest) {
 }
 
 /**
- * Mock form field values via Schema.mock and update the run context.
+ * Mock form field values via Schema.mock, apply optional overrides, and update the run context.
  *
  * @param {import('@ossy/schema').Schema} engine
  * @param {{ id: string, fields?: { name: string, type?: string }[] }} template
  * @param {FlowRunContext} context
+ * @param {Record<string, unknown>} [fieldOverrides]
  */
-function mockFormContent (engine, template, context) {
-  const content = engine.mock(template, { faker })
+function mockFormContent (engine, template, context, fieldOverrides) {
+  const mocked = engine.mock(template, { faker })
+  const content = applyFormFieldOverrides(mocked, fieldOverrides, context)
   for (const field of template.fields ?? []) {
+    // Skip upload/reference mocks — they are not DOM-fillable and must not be
+    // restored onto file inputs during remount-safe action submits.
+    if (['file', 'image', 'reference'].includes(field.type)) continue
     const value = content[field.name]
     if (value !== undefined) context.fields[field.name] = value
     if (field.type === 'email' || field.name?.toLowerCase?.().includes('email')) {
@@ -110,23 +131,6 @@ function mockFormContent (engine, template, context) {
   return content
 }
 
-function resolveActionId (action) {
-  if (typeof action === 'string') return action
-  if (action && typeof action.id === 'string') return action.id
-  throw new Error('Flow action step requires an action POJO or id string')
-}
-
-function actionSelector (actionId, service) {
-  return service
-    ? `[data-action="${actionId}"][data-service="${service}"]`
-    : `[data-action="${actionId}"]`
-}
-
-function resolveActionService (action, fallback) {
-  if (typeof action === 'object' && action.service) return action.service
-  return fallback
-}
-
 function resolveContextObject (obj, context) {
   if (!obj || typeof obj !== 'object') return obj
   const out = {}
@@ -232,6 +236,67 @@ export async function runFlow (flow, options = {}) {
       continue
     }
 
+    if (step.files != null) {
+      if (!page) throw new Error('files step requires a Playwright page')
+      const { selector, payloads } = resolveFilesTarget(step.files)
+      const resolvedSelector = interpolateContextString(selector, context, {
+        escape: escapeCssAttrValue,
+      })
+      const locator = page.locator(resolvedSelector).first()
+      const filesTimeout = step.timeout ?? 15000
+      // File inputs are often visually hidden behind dropzones — attach is enough.
+      await locator.waitFor({ state: 'attached', timeout: filesTimeout })
+      // SSR markup is attached before React wires onChange. Settle like action clicks.
+      await page.evaluate(async () => {
+        await new Promise((resolve) => {
+          requestAnimationFrame(() => requestAnimationFrame(resolve))
+        })
+        await new Promise((resolve) => setTimeout(resolve, 500))
+      })
+
+      // Path payloads use Playwright's setInputFiles. In-memory buffer payloads use
+      // DataTransfer — Playwright setInputFiles populates input.files but does not
+      // notify React 19's onChange for this input; assigning via DataTransfer + change does.
+      const pathPayloads = payloads.filter((p) => typeof p === 'string')
+      const bufferPayloads = payloads.filter((p) => typeof p === 'object' && p != null)
+      if (pathPayloads.length) {
+        await locator.setInputFiles(pathPayloads)
+      }
+      if (bufferPayloads.length) {
+        await locator.evaluate((el, files) => {
+          if (!(el instanceof HTMLInputElement) || el.type !== 'file') {
+            throw new Error('files step selector must resolve to an HTML file input')
+          }
+          const dt = new DataTransfer()
+          for (const file of files) {
+            const bytes = Uint8Array.from(atob(file.base64), (c) => c.charCodeAt(0))
+            dt.items.add(new File([bytes], file.name, { type: file.mimeType }))
+          }
+          el.files = dt.files
+          el.dispatchEvent(new Event('input', { bubbles: true }))
+          el.dispatchEvent(new Event('change', { bubbles: true }))
+        }, bufferPayloads.map((p) => ({
+          name: p.name,
+          mimeType: p.mimeType,
+          base64: Buffer.from(p.buffer).toString('base64'),
+        })))
+      } else if (pathPayloads.length) {
+        // Paths-only: nudge change in case the host needs an explicit event.
+        await locator.evaluate((el) => {
+          if (!(el instanceof HTMLInputElement) || el.type !== 'file') return
+          el.dispatchEvent(new Event('input', { bubbles: true }))
+          el.dispatchEvent(new Event('change', { bubbles: true }))
+        }).catch(() => {})
+      }
+
+      // Capture the first uploaded filename for later result assertions.
+      const firstName = typeof payloads[0] === 'string'
+        ? path.basename(payloads[0])
+        : payloads[0]?.name
+      if (firstName) context.uploadedFileName = firstName
+      continue
+    }
+
     if (step.form) {
       if (!page) throw new Error('form step requires a Playwright page')
       const formMeta = step.form
@@ -245,11 +310,13 @@ export async function runFlow (flow, options = {}) {
         throw new Error(`Resource schema "${schemaId}" not found or has no fields`)
       }
       const engine = schemaEngineFromManifest(manifest)
-      const content = mockFormContent(engine, template, context)
+      // Optional field overrides: `{ form: SignInForm, fields: { email: '$email' } }`
+      const content = mockFormContent(engine, template, context, step.fields)
       const formTimeout = step.timeout ?? 15000
       const formRoot = formId ? page.locator(`form[id="${formId}"]`) : page
       await formRoot.waitFor({ state: 'visible', timeout: formTimeout })
-      for (const field of template.fields) {
+
+      const fillField = async (field) => {
         const value = content[field.name]
         if (value === undefined || value === null) {
           throw new Error(`mockFormContent produced no value for field "${field.name}"`)
@@ -259,58 +326,218 @@ export async function runFlow (flow, options = {}) {
         const tag = await locator.evaluate(el => el.tagName.toLowerCase()).catch(() => 'input')
         if (tag === 'select') {
           await locator.selectOption(String(value))
-        } else if (tag === 'input') {
+          return
+        }
+        if (tag === 'input') {
           const inputType = await locator.getAttribute('type')
           if (inputType === 'checkbox') {
             if (value) await locator.check()
-          } else {
-            // Retry fills: early hydration can accept DOM input then wipe on re-render.
-            const asText = String(value)
-            for (let attempt = 0; attempt < 3; attempt++) {
-              await locator.fill(asText)
-              try {
-                await expectFn(locator).toHaveValue(asText, { timeout: 2000 })
-                break
-              } catch (err) {
-                if (attempt === 2) throw err
-                await page.waitForTimeout(150)
-              }
-            }
+            else await locator.uncheck()
+            return
+          }
+        }
+        // Retry fills: early hydration / sibling controlled updates can wipe earlier fields.
+        const asText = String(value)
+        for (let attempt = 0; attempt < 3; attempt++) {
+          await locator.fill(asText)
+          // Blur so React controlled state commits before the next field fill.
+          await locator.blur().catch(() => {})
+          try {
+            await expectFn(locator).toHaveValue(asText, { timeout: 2000 })
+            return
+          } catch (err) {
+            if (attempt === 2) throw err
+            await page.waitForTimeout(150)
           }
-        } else {
-          await locator.fill(String(value))
         }
       }
+
+      // File / reference / image fields need real uploads — skip in declarative fills.
+      const fillableFields = (template.fields ?? []).filter(
+        (field) => !['file', 'image', 'reference'].includes(field.type),
+      )
+
+      for (const field of fillableFields) {
+        await fillField(field)
+      }
+
+      // Sibling controlled re-renders can clear earlier inputs after later fills —
+      // re-assert text-like fields and repair any that drifted.
+      for (let settle = 0; settle < 3; settle++) {
+        let drifted = false
+        for (const field of fillableFields) {
+          const value = content[field.name]
+          if (value === undefined || value === null) continue
+          const locator = formRoot.locator(`[name="${field.name}"]`).first()
+          const tag = await locator.evaluate(el => el.tagName.toLowerCase()).catch(() => 'input')
+          if (tag === 'select') continue
+          if (tag === 'input') {
+            const inputType = await locator.getAttribute('type')
+            if (inputType === 'checkbox' || inputType === 'file') continue
+          }
+          const asText = String(value)
+          const current = await locator.inputValue().catch(() => '')
+          if (current !== asText) {
+            drifted = true
+            await fillField(field)
+          }
+        }
+        if (!drifted) break
+        if (settle === 2) {
+          throw new Error(`form step could not keep field values stable for "${formId}"`)
+        }
+        await page.waitForTimeout(150)
+      }
       continue
     }
 
     if (step.action != null) {
       if (!page) throw new Error('action step requires a Playwright page')
-      const actionId = resolveActionId(step.action)
-      const service = resolveActionService(step.action, step.service)
-      const matches = page.locator(actionSelector(actionId, service))
+      const actionStep = typeof step.action === 'object' && step.action != null
+        ? resolveContextObject(step.action, context)
+        : step.action
+      const actionId = resolveActionId(actionStep)
+      const matchers = resolveActionMatchers(actionStep, {
+        service: resolveContextValue(step.service, context),
+        memberEmail: resolveContextValue(step.memberEmail, context),
+        language: resolveContextValue(step.language, context),
+      })
+      const selector = actionSelector(actionId, matchers)
       const actionTimeout = step.timeout ?? 15000
-      await matches.first().waitFor({ state: 'attached', timeout: actionTimeout })
+      const actionDeadline = Date.now() + actionTimeout
+      // SSR markup is visible before React attaches onClick. Wait a paint+microtask
+      // so hydration can finish; then use DOM click() (Playwright pointer clicks can
+      // miss React handlers when overlays intercept hit-testing).
+      //
+      // Re-query the live node after the settle wait: concurrent auth/workspace
+      // fetches can remount the tree and detach Playwright locators mid-scroll
+      // (and wipe uncontrolled form state). Retry within the action timeout.
       // Prefer an actionable match when duplicates exist (e.g. hero CTA under a page overlay).
-      const count = await matches.count()
       let clicked = false
       let lastError
-      for (let i = 0; i < count; i++) {
-        const candidate = matches.nth(i)
+      while (!clicked && Date.now() < actionDeadline) {
+        const remaining = Math.max(250, actionDeadline - Date.now())
+        const matches = page.locator(selector)
         try {
-          await candidate.click({ timeout: Math.min(5000, actionTimeout) })
-          clicked = true
-          break
+          await matches.first().waitFor({ state: 'attached', timeout: remaining })
         } catch (err) {
           lastError = err
+          break
+        }
+        const count = await matches.count()
+        for (let i = 0; i < count; i++) {
+          const candidate = matches.nth(i)
+          try {
+            await candidate.waitFor({
+              state: 'visible',
+              timeout: Math.min(5000, Math.max(250, actionDeadline - Date.now())),
+            })
+            // Scroll inside evaluate via a fresh querySelector — Playwright's
+            // scrollIntoViewIfNeeded holds a locator through a stability wait and
+            // throws "not attached" when GetWorkspace remounts PackageServiceToggle.
+            const fieldRestore = { ...(context.fields ?? {}) }
+            if (context.email != null && fieldRestore.email == null) {
+              fieldRestore.email = context.email
+            }
+            await page.evaluate(async ({ selector: sel, fields }) => {
+              await new Promise((resolve) => {
+                requestAnimationFrame(() => requestAnimationFrame(resolve))
+              })
+              await new Promise((resolve) => setTimeout(resolve, 500))
+              const el = document.querySelector(sel)
+              if (!el) throw new Error(`Action control disappeared after settle: ${sel}`)
+              if (typeof el.scrollIntoView === 'function') {
+                el.scrollIntoView({ block: 'nearest', inline: 'nearest' })
+              }
+              const form = el.closest('form')
+              if (form && fields && typeof fields === 'object') {
+                for (const [name, value] of Object.entries(fields)) {
+                  if (value == null || typeof value === 'object') continue
+                  const input = form.querySelector(`[name="${name}"]`)
+                  if (!input || input.disabled) continue
+                  // File inputs throw InvalidStateError if value is set programmatically.
+                  if (input instanceof HTMLInputElement && input.type === 'file') continue
+                  const asText = String(value)
+                  if (input.value === asText) continue
+                  const proto = Object.getPrototypeOf(input)
+                  const desc = Object.getOwnPropertyDescriptor(proto, 'value')
+                  desc?.set?.call(input, asText)
+                  input.dispatchEvent(new Event('input', { bubbles: true }))
+                  input.dispatchEvent(new Event('change', { bubbles: true }))
+                }
+              }
+              const isSubmit = form && (
+                (el instanceof HTMLButtonElement && el.type === 'submit')
+                || el.getAttribute('type') === 'submit'
+              )
+              if (isSubmit && typeof form.requestSubmit === 'function') {
+                form.requestSubmit(el)
+              } else if (typeof el.click === 'function') {
+                el.click()
+              } else {
+                el.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true, view: window }))
+              }
+            }, { selector, fields: fieldRestore })
+            clicked = true
+            break
+          } catch (err) {
+            lastError = err
+            const message = String(err?.message ?? err)
+            if (/not attached|disappeared after settle/i.test(message)) {
+              await page.waitForTimeout(100)
+              break
+            }
+          }
+        }
+        if (!clicked && Date.now() < actionDeadline) {
+          await page.waitForTimeout(100)
         }
       }
       if (!clicked) {
-        throw lastError ?? new Error(`No actionable locator for ${actionSelector(actionId, service)}`)
+        throw lastError ?? new Error(`No actionable locator for ${selector}`)
       }
       continue
     }
 
+    if (step.download != null) {
+      if (!page) throw new Error('download step requires a Playwright page')
+      const target = resolveDownloadTarget(step.download)
+      const timeout = step.timeout ?? target.timeout
+      const locator = target.actionId
+        ? page.locator(actionSelector(target.actionId, target.service))
+        : page.locator(target.selector)
+      await locator.first().waitFor({ state: 'visible', timeout })
+
+      // Collect downloads via one listener — parallel waitForEvent('download')
+      // waiters all resolve on the *first* event (Playwright EventEmitter fan-out).
+      const downloads = []
+      const onDownload = (download) => {
+        downloads.push(download)
+      }
+      page.on('download', onDownload)
+      try {
+        await locator.first().scrollIntoViewIfNeeded()
+        await locator.first().click({ timeout })
+        const deadline = Date.now() + timeout
+        while (downloads.length < target.count) {
+          if (Date.now() > deadline) {
+            throw new Error(
+              `Timed out waiting for ${target.count} download(s); got ${downloads.length}`,
+            )
+          }
+          await page.waitForTimeout(50)
+        }
+      } finally {
+        page.off('download', onDownload)
+      }
+
+      const suggested = downloads.slice(0, target.count).map((download) => download.suggestedFilename())
+      assertDownloadFilenames(suggested, target.filenames)
+      context.downloads = suggested
+      if (suggested[0]) context.downloadedFileName = suggested[0]
+      continue
+    }
+
     if (step.capture != null) {
       if (!page) throw new Error('capture step requires a Playwright page')
       for (const [key, spec] of Object.entries(step.capture)) {
@@ -353,8 +580,12 @@ export async function runFlow (flow, options = {}) {
       let clicked = false
       while (Date.now() < deadline && !clicked) {
         await page.goto(inboxUrl)
-        const link = page.getByRole('link', { name: pattern }).first()
+        // Scope to email HTML body so chrome auth links (e.g. header "Sign in")
+        // cannot steal the click when the CTA label collides.
+        const body = page.locator('[data-email-body]').first()
+        const link = body.getByRole('link', { name: pattern }).first()
         try {
+          await body.waitFor({ state: 'visible', timeout: 2000 })
           await link.waitFor({ state: 'visible', timeout: 2000 })
           await Promise.all([
             page.waitForLoadState('domcontentloaded'),
@@ -390,9 +621,16 @@ export async function runFlow (flow, options = {}) {
         await expectFn(locator).toBeVisible({ timeout })
       }
       if (action != null) {
-        const actionId = resolveActionId(action)
-        const service = resolveActionService(action, step.result.service)
-        await assertLocator(page.locator(actionSelector(actionId, service)).first())
+        const actionResult = typeof action === 'object' && action != null
+          ? resolveContextObject(action, context)
+          : action
+        const actionId = resolveActionId(actionResult)
+        const matchers = resolveActionMatchers(actionResult, {
+          service: resolveContextValue(step.result.service, context),
+          memberEmail: resolveContextValue(step.result.memberEmail, context),
+          language: resolveContextValue(step.result.language, context),
+        })
+        await assertLocator(page.locator(actionSelector(actionId, matchers)).first())
       }
       if (selector != null) {
         const resolvedSelector = interpolateContextString(selector, context, {
@@ -463,6 +701,9 @@ export function registerFlow (mod, options = {}) {
 
   test.describe(feature, () => {
     test(title, async ({ page, baseURL }) => {
+      if (typeof meta.timeout === 'number' && meta.timeout > 0) {
+        test.setTimeout(meta.timeout)
+      }
       const manifestPath = options.manifestPath
       const manifest = manifestPath ? loadManifest(manifestPath) : undefined
       await runFlow({ ...flowBody, steps, metadata: meta }, {

package/src/user-app-settings.js

@@ -1,35 +1,96 @@
 export const USER_SETTINGS_COOKIE = 'x-ossy-user-settings'
+export const WORKSPACE_ID_COOKIE = 'x-ossy-workspace-id'
 export const AUTH_COOKIE = 'auth'
 
 const USER_SETTINGS_MAX_AGE_MS = 2147483647
 const AUTH_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000
 
+const signedCookieOpts = {
+  httpOnly: true,
+  signed: true,
+  path: '/',
+}
+
+function settingsCookieExpires () {
+  return new Date(Date.now() + USER_SETTINGS_MAX_AGE_MS)
+}
+
 export function readUserAppSettings (req) {
   return JSON.parse(req.signedCookies?.[USER_SETTINGS_COOKIE] || '{}')
 }
 
+/**
+ * Active workspace id: dedicated cookie (select-workspace / sign-in) wins over the
+ * legacy field inside x-ossy-user-settings. Shell Sync PATCH must not clobber the
+ * dedicated cookie — see mergeUserAppSettingsCookie.
+ */
+export function readWorkspaceIdFromCookies (req) {
+  const dedicated = req.signedCookies?.[WORKSPACE_ID_COOKIE]
+  if (dedicated && typeof dedicated === 'string' && dedicated !== 'undefined') {
+    return dedicated
+  }
+  const fromSettings = readUserAppSettings(req).workspaceId
+  if (fromSettings && typeof fromSettings === 'string' && fromSettings !== 'undefined') {
+    return fromSettings
+  }
+  return undefined
+}
+
+export function setWorkspaceIdCookie (res, workspaceId) {
+  res.cookie(WORKSPACE_ID_COOKIE, String(workspaceId), {
+    ...signedCookieOpts,
+    expires: settingsCookieExpires(),
+  })
+}
+
+export function clearWorkspaceIdCookie (res) {
+  const clearOpts = { httpOnly: true, path: '/' }
+  res.clearCookie(WORKSPACE_ID_COOKIE, clearOpts)
+  res.clearCookie(WORKSPACE_ID_COOKIE, { ...clearOpts, signed: true })
+  res.cookie(WORKSPACE_ID_COOKIE, '', {
+    ...clearOpts,
+    signed: true,
+    expires: new Date(0),
+  })
+}
+
 export function mergeUserAppSettingsCookie (req, res, partial) {
-  const updated = { ...readUserAppSettings(req), ...partial }
+  const current = readUserAppSettings(req)
+  const updated = { ...current, ...partial }
+  const explicitWorkspaceId = Object.prototype.hasOwnProperty.call(partial, 'workspaceId')
+
+  if (explicitWorkspaceId) {
+    if (partial.workspaceId) {
+      setWorkspaceIdCookie(res, partial.workspaceId)
+      updated.workspaceId = partial.workspaceId
+    } else {
+      clearWorkspaceIdCookie(res)
+      delete updated.workspaceId
+    }
+  } else {
+    // Shell Sync and similar patches omit workspaceId. Never rewrite it from the
+    // request's cookie snapshot — an in-flight PATCH started before select-workspace
+    // would otherwise clobber the newly selected workspace (Switch workspace e2e flake).
+    delete updated.workspaceId
+  }
+
   res.cookie(USER_SETTINGS_COOKIE, JSON.stringify(updated), {
-    httpOnly: true,
-    signed: true,
-    path: '/',
-    expires: new Date(Date.now() + USER_SETTINGS_MAX_AGE_MS),
+    ...signedCookieOpts,
+    expires: settingsCookieExpires(),
   })
 }
 
 export function clearWorkspaceFromUserAppSettings (req, res) {
   const settings = readUserAppSettings(req)
   delete settings.workspaceId
+  clearWorkspaceIdCookie(res)
   if (Object.keys(settings).length === 0) {
     res.clearCookie(USER_SETTINGS_COOKIE, { httpOnly: true, signed: true, path: '/' })
     return
   }
   res.cookie(USER_SETTINGS_COOKIE, JSON.stringify(settings), {
-    httpOnly: true,
-    signed: true,
-    path: '/',
-    expires: new Date(Date.now() + USER_SETTINGS_MAX_AGE_MS),
+    ...signedCookieOpts,
+    expires: settingsCookieExpires(),
   })
 }