@open-mercato/ai-assistant 0.5.1-develop.3036.f02c281f23 → 0.5.1-develop.3045.b4b3320cc2

package/src/modules/ai_assistant/__tests__/integration/pending-action-contract.test.ts

@@ -0,0 +1,1015 @@
+/**
+ * Step 5.17 — Phase 3 WS-D integration tests for the pending-action contract.
+ *
+ * Closes the Step 5.5 → 5.12 surface with a Jest-integration suite that drives
+ * the confirm executor (Step 5.8), cancel executor (Step 5.9), cleanup worker
+ * (Step 5.12), and the shared re-check orchestrator (Step 5.8) against a
+ * repository stub that mirrors the production state-machine guard. Event
+ * emissions are asserted against the typed Step 5.11 `emitAiAssistantEvent`
+ * contract via per-executor injection seams — no live LLM, no real DB, no
+ * real event bus.
+ *
+ * Mocks sit at narrow boundaries:
+ * - ORM: a hand-rolled in-memory `AiPendingActionRepository` shim that honors
+ *   `AI_PENDING_ACTION_ALLOWED_TRANSITIONS` so illegal edges throw
+ *   `AiPendingActionStateError`, just like the real repo.
+ * - Event bus: the `emitEvent` seam already present on every executor; we
+ *   assert the event id + payload shape directly.
+ *
+ * The pending-action executor, cancel helper, re-check orchestrator, and
+ * cleanup worker themselves are under test and MUST NOT be mocked.
+ */
+import { z } from 'zod'
+import type { AwilixContainer } from 'awilix'
+import type { AiPendingAction } from '../../data/entities'
+import type { AiAgentDefinition } from '../../lib/ai-agent-definition'
+import type {
+  AiPendingActionExecutionResult,
+  AiPendingActionFailedRecord,
+  AiPendingActionRecordDiff,
+  AiPendingActionStatus,
+} from '../../lib/pending-action-types'
+import {
+  AI_PENDING_ACTION_ALLOWED_TRANSITIONS,
+  AiPendingActionStateError,
+} from '../../lib/pending-action-types'
+import type { AiToolDefinition, McpToolContext } from '../../lib/types'
+import {
+  executePendingActionConfirm,
+  PENDING_ACTION_CONFIRMED_EVENT_ID,
+} from '../../lib/pending-action-executor'
+import {
+  executePendingActionCancel,
+  PENDING_ACTION_CANCELLED_EVENT_ID,
+  PENDING_ACTION_EXPIRED_EVENT_ID,
+} from '../../lib/pending-action-cancel'
+import { runPendingActionRechecks } from '../../lib/pending-action-recheck'
+import { runPendingActionCleanup } from '../../workers/ai-pending-action-cleanup'
+import type {
+  AiActionCancelledPayload,
+  AiActionConfirmedPayload,
+  AiActionExpiredPayload,
+} from '../../events'
+import { resolveEffectiveMutationPolicy } from '../../lib/agent-policy'
+
+// The recheck layer dynamic-imports the core Attachment entity for the
+// cross-tenant attachment guard. The core dist build is shipped as ESM and
+// ts-jest does not transform it, so we replace the module with a minimal
+// mock that gives the recheck a stable class reference.
+jest.mock(
+  '@open-mercato/core/modules/attachments/data/entities',
+  () => ({ Attachment: class MockAttachment {} }),
+  { virtual: true },
+)
+
+// findWithDecryption is used by the recheck's attachment scope guard. The
+// integration mock returns an attachment row from a foreign tenant so the
+// guard's cross-tenant assertion fires without a real DB.
+jest.mock('@open-mercato/shared/lib/encryption/find', () => {
+  const actual = jest.requireActual('@open-mercato/shared/lib/encryption/find')
+  return {
+    ...actual,
+    findWithDecryption: jest.fn(
+      async (_em: unknown, _entity: unknown, where: { id?: { $in: string[] } }) => {
+        const ids = where?.id?.$in ?? []
+        return ids.map((id: string) => ({
+          id,
+          tenantId: 'tenant-other',
+          organizationId: null,
+        }))
+      },
+    ),
+  }
+})
+
+// --- Fixtures -------------------------------------------------------------
+
+type Row = AiPendingAction & Record<string, unknown>
+
+interface ActionSeed {
+  id?: string
+  tenantId?: string
+  organizationId?: string | null
+  status?: AiPendingActionStatus
+  agentId?: string
+  toolName?: string
+  expiresAt?: Date
+  recordVersion?: string | null
+  records?: AiPendingActionRecordDiff[] | null
+  attachmentIds?: string[]
+  executionResult?: AiPendingActionExecutionResult | null
+}
+
+const REFERENCE_CLOCK = new Date('2026-04-18T10:00:00.000Z')
+
+function makeSeed(seed: ActionSeed = {}): Row {
+  return {
+    id: seed.id ?? 'pa_1',
+    tenantId: seed.tenantId ?? 'tenant-a',
+    organizationId: seed.organizationId === undefined ? 'org-a' : seed.organizationId,
+    agentId: seed.agentId ?? 'catalog.merchandising_assistant',
+    toolName: seed.toolName ?? 'catalog.update_product',
+    status: (seed.status ?? 'pending') as AiPendingActionStatus,
+    fieldDiff: [],
+    records: seed.records ?? null,
+    failedRecords: null,
+    sideEffectsSummary: null,
+    recordVersion: seed.recordVersion === undefined ? 'v-1' : seed.recordVersion,
+    attachmentIds: seed.attachmentIds ?? [],
+    normalizedInput: { productId: 'p-1', patch: { title: 'New' } },
+    queueMode: 'inline',
+    executionResult: seed.executionResult ?? null,
+    targetEntityType: 'product',
+    targetRecordId: 'p-1',
+    conversationId: null,
+    idempotencyKey: `idem_${seed.id ?? 'pa_1'}`,
+    createdByUserId: 'user-a',
+    createdAt: new Date('2026-04-18T09:00:00.000Z'),
+    expiresAt: seed.expiresAt ?? new Date('2026-04-18T11:00:00.000Z'),
+    resolvedAt: null,
+    resolvedByUserId: null,
+  } as unknown as Row
+}
+
+function makeAgent(
+  overrides: Partial<AiAgentDefinition> = {},
+): AiAgentDefinition {
+  return {
+    id: 'catalog.merchandising_assistant',
+    moduleId: 'catalog',
+    label: 'Catalog Merchandising Assistant',
+    description: 'Updates product titles, descriptions, media, prices.',
+    systemPrompt: 'System',
+    allowedTools: ['catalog.update_product'],
+    readOnly: false,
+    mutationPolicy: 'confirm-required',
+    requiredFeatures: [],
+    ...overrides,
+  } as AiAgentDefinition
+}
+
+function makeTool(
+  overrides: Partial<AiToolDefinition> = {},
+): AiToolDefinition {
+  return {
+    name: 'catalog.update_product',
+    description: 'Update product',
+    inputSchema: z.object({
+      productId: z.string(),
+      patch: z.object({}).passthrough(),
+    }),
+    handler: async () => ({
+      recordId: 'p-1',
+      commandName: 'catalog.product.update',
+    }),
+    isMutation: true,
+    ...overrides,
+  } as AiToolDefinition
+}
+
+function makeContainer(): AwilixContainer {
+  return {
+    resolve: (name: string) => {
+      if (name === 'em') return {}
+      throw new Error(`unexpected dep: ${name}`)
+    },
+  } as unknown as AwilixContainer
+}
+
+function makeExecCtx(overrides: Partial<{
+  tenantId: string
+  organizationId: string | null
+  userId: string
+  userFeatures: string[]
+  isSuperAdmin: boolean
+}> = {}) {
+  return {
+    tenantId: overrides.tenantId ?? 'tenant-a',
+    organizationId:
+      overrides.organizationId === undefined ? 'org-a' : overrides.organizationId,
+    userId: overrides.userId ?? 'user-a',
+    userFeatures: overrides.userFeatures ?? ['ai_assistant.view'],
+    isSuperAdmin: overrides.isSuperAdmin ?? false,
+    container: makeContainer(),
+  }
+}
+
+function makeCancelCtx(overrides: Partial<{
+  tenantId: string
+  organizationId: string | null
+  userId: string
+}> = {}) {
+  return {
+    tenantId: overrides.tenantId ?? 'tenant-a',
+    organizationId:
+      overrides.organizationId === undefined ? 'org-a' : overrides.organizationId,
+    userId: overrides.userId ?? 'user-a',
+    container: makeContainer(),
+  }
+}
+
+function makeAuthCtx(overrides: Partial<{
+  tenantId: string
+  organizationId: string | null
+  userId: string
+  userFeatures: string[]
+  isSuperAdmin: boolean
+}> = {}) {
+  return {
+    tenantId: overrides.tenantId ?? 'tenant-a',
+    organizationId:
+      overrides.organizationId === undefined ? 'org-a' : overrides.organizationId,
+    userId: overrides.userId ?? 'user-a',
+    userFeatures: overrides.userFeatures ?? ['ai_assistant.view'],
+    isSuperAdmin: overrides.isSuperAdmin ?? false,
+  }
+}
+
+// --- In-memory repo that mirrors the production state-machine ---------------
+
+interface RepoStubOptions {
+  seeds: Row[]
+}
+
+interface ScopeFilter {
+  tenantId: string
+  organizationId?: string | null
+}
+
+function matchesScope(row: Row, scope: ScopeFilter): boolean {
+  if (row.tenantId !== scope.tenantId) return false
+  const expectedOrg = scope.organizationId ?? null
+  if ((row.organizationId ?? null) !== expectedOrg) return false
+  return true
+}
+
+function makeRepoStub(options: RepoStubOptions) {
+  const store = new Map<string, Row>()
+  for (const row of options.seeds) {
+    store.set(row.id as string, { ...row })
+  }
+
+  const getById = jest.fn(async (id: string, scope: ScopeFilter) => {
+    const row = store.get(id)
+    if (!row) return null
+    if (!matchesScope(row, scope)) return null
+    return row
+  })
+
+  const setStatus = jest.fn(
+    async (
+      id: string,
+      next: AiPendingActionStatus,
+      scope: ScopeFilter,
+      extra?: {
+        now?: Date
+        resolvedByUserId?: string | null
+        executionResult?: AiPendingActionExecutionResult | null
+        failedRecords?: AiPendingActionFailedRecord[] | null
+      },
+    ) => {
+      const existing = store.get(id)
+      if (!existing || !matchesScope(existing, scope)) {
+        throw new Error(`row ${id} not found`)
+      }
+      if (existing.status === next) return existing
+      const allowed = AI_PENDING_ACTION_ALLOWED_TRANSITIONS[existing.status] ?? []
+      if (!allowed.includes(next)) {
+        throw new AiPendingActionStateError(existing.status, next)
+      }
+      const now = extra?.now ?? new Date()
+      existing.status = next
+      if (
+        next === 'confirmed' ||
+        next === 'cancelled' ||
+        next === 'expired' ||
+        next === 'failed'
+      ) {
+        existing.resolvedAt = (existing.resolvedAt ?? now) as never
+        if (extra && Object.prototype.hasOwnProperty.call(extra, 'resolvedByUserId')) {
+          existing.resolvedByUserId = (extra.resolvedByUserId ?? null) as never
+        } else if (next === 'expired') {
+          existing.resolvedByUserId = null as never
+        }
+      }
+      if (extra && Object.prototype.hasOwnProperty.call(extra, 'executionResult')) {
+        existing.executionResult = (extra.executionResult ?? null) as never
+      }
+      if (extra && Object.prototype.hasOwnProperty.call(extra, 'failedRecords')) {
+        existing.failedRecords = (extra.failedRecords ?? null) as never
+      }
+      return existing
+    },
+  )
+
+  const listExpired = jest.fn(
+    async (scope: ScopeFilter, now: Date, limit: number) => {
+      return Array.from(store.values())
+        .filter((row) => matchesScope(row, scope))
+        .filter((row) => row.status === 'pending')
+        .filter((row) => (row.expiresAt as Date).getTime() < now.getTime())
+        .sort((a, b) => (a.expiresAt as Date).getTime() - (b.expiresAt as Date).getTime())
+        .slice(0, limit)
+    },
+  )
+
+  return {
+    repo: {
+      getById,
+      setStatus,
+      listExpired,
+    } as unknown as import('../../data/repositories/AiPendingActionRepository').AiPendingActionRepository,
+    getById,
+    setStatus,
+    listExpired,
+    store,
+  }
+}
+
+// --- Suite ------------------------------------------------------------------
+
+describe('Pending-action contract integration (Step 5.17)', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  // Scenario 1 --------------------------------------------------------------
+  it('scenario-1 happy path: pending → executing → confirmed with executionResult.recordId, single ai.action.confirmed', async () => {
+    const seed = makeSeed()
+    const { repo, setStatus, store } = makeRepoStub({ seeds: [seed] })
+    const emit = jest.fn().mockResolvedValue(undefined)
+
+    const result = await executePendingActionConfirm({
+      action: store.get('pa_1')!,
+      agent: makeAgent(),
+      tool: makeTool(),
+      ctx: makeExecCtx(),
+      repo,
+      emitEvent: emit,
+      now: REFERENCE_CLOCK,
+    })
+
+    expect(result.ok).toBe(true)
+    expect(result.executionResult).toEqual({
+      recordId: 'p-1',
+      commandName: 'catalog.product.update',
+    })
+    const transitions = setStatus.mock.calls.map((call) => call[1])
+    expect(transitions).toEqual(['confirmed', 'executing', 'confirmed'])
+    expect(store.get('pa_1')!.status).toBe('confirmed')
+    expect(store.get('pa_1')!.resolvedAt).toBeTruthy()
+    expect(store.get('pa_1')!.resolvedByUserId).toBe('user-a')
+
+    expect(emit).toHaveBeenCalledTimes(1)
+    const [emittedId, emittedPayload] = emit.mock.calls[0] as [
+      'ai.action.confirmed',
+      AiActionConfirmedPayload,
+    ]
+    expect(emittedId).toBe(PENDING_ACTION_CONFIRMED_EVENT_ID)
+    expect(emittedPayload).toMatchObject({
+      pendingActionId: 'pa_1',
+      agentId: 'catalog.merchandising_assistant',
+      toolName: 'catalog.update_product',
+      status: 'confirmed',
+      tenantId: 'tenant-a',
+      organizationId: 'org-a',
+      userId: 'user-a',
+      resolvedByUserId: 'user-a',
+      executionResult: {
+        recordId: 'p-1',
+        commandName: 'catalog.product.update',
+      },
+    })
+    expect(typeof emittedPayload.resolvedAt).toBe('string')
+  })
+
+  // Scenario 2 --------------------------------------------------------------
+  it('scenario-2 cancel: pending → cancelled with reason; executionResult.error.code=cancelled_by_user, one ai.action.cancelled', async () => {
+    const seed = makeSeed()
+    const { repo, store } = makeRepoStub({ seeds: [seed] })
+    const emit = jest.fn().mockResolvedValue(undefined)
+
+    const result = await executePendingActionCancel({
+      action: store.get('pa_1')!,
+      ctx: makeCancelCtx(),
+      reason: 'Operator aborted',
+      repo,
+      emitEvent: emit,
+      now: REFERENCE_CLOCK,
+    })
+
+    expect(result.status).toBe('cancelled')
+    expect(result.row.status).toBe('cancelled')
+    expect(store.get('pa_1')!.status).toBe('cancelled')
+    expect(store.get('pa_1')!.resolvedByUserId).toBe('user-a')
+    expect(store.get('pa_1')!.resolvedAt).toBeTruthy()
+    expect(store.get('pa_1')!.executionResult).toMatchObject({
+      error: { code: 'cancelled_by_user', message: 'Operator aborted' },
+    })
+
+    expect(emit).toHaveBeenCalledTimes(1)
+    const [emittedId, emittedPayload] = emit.mock.calls[0] as [
+      'ai.action.cancelled',
+      AiActionCancelledPayload,
+    ]
+    expect(emittedId).toBe(PENDING_ACTION_CANCELLED_EVENT_ID)
+    expect(emittedPayload).toMatchObject({
+      pendingActionId: 'pa_1',
+      status: 'cancelled',
+      resolvedByUserId: 'user-a',
+      reason: 'Operator aborted',
+    })
+  })
+
+  // Scenario 3 --------------------------------------------------------------
+  it('scenario-3 expiry via cleanup worker: pending (past expiresAt) → expired, worker emits ai.action.expired, resolvedByUserId=null', async () => {
+    const past = new Date(REFERENCE_CLOCK.getTime() - 60 * 60 * 1000)
+    const seed = makeSeed({ expiresAt: past })
+    const { repo, listExpired, setStatus, store } = makeRepoStub({ seeds: [seed] })
+    const emit = jest.fn().mockResolvedValue(undefined)
+
+    const summary = await runPendingActionCleanup({
+      em: {} as never,
+      repo,
+      emitEvent: emit as never,
+      now: REFERENCE_CLOCK,
+      discoverTenants: async () => [
+        { tenantId: 'tenant-a', organizationId: 'org-a' },
+      ],
+    })
+
+    expect(summary.rowsExpired).toBe(1)
+    expect(summary.rowsSkipped).toBe(0)
+    expect(summary.rowsErrored).toBe(0)
+    expect(listExpired).toHaveBeenCalled()
+    expect(setStatus).toHaveBeenCalledWith(
+      'pa_1',
+      'expired',
+      expect.objectContaining({ tenantId: 'tenant-a', organizationId: 'org-a' }),
+      expect.objectContaining({ resolvedByUserId: null }),
+    )
+    expect(store.get('pa_1')!.status).toBe('expired')
+    expect(store.get('pa_1')!.resolvedByUserId).toBeNull()
+
+    expect(emit).toHaveBeenCalledTimes(1)
+    const [emittedId, emittedPayload] = emit.mock.calls[0] as [
+      'ai.action.expired',
+      AiActionExpiredPayload,
+    ]
+    expect(emittedId).toBe(PENDING_ACTION_EXPIRED_EVENT_ID)
+    expect(emittedPayload).toMatchObject({
+      pendingActionId: 'pa_1',
+      status: 'expired',
+      resolvedByUserId: null,
+      tenantId: 'tenant-a',
+      organizationId: 'org-a',
+    })
+    expect(typeof emittedPayload.resolvedAt).toBe('string')
+    expect(typeof emittedPayload.expiresAt).toBe('string')
+  })
+
+  // Scenario 4 --------------------------------------------------------------
+  it('scenario-4 expiry via opportunistic cancel path: past expiresAt flips pending → expired atomically and emits ai.action.expired', async () => {
+    const past = new Date(REFERENCE_CLOCK.getTime() - 60 * 60 * 1000)
+    const seed = makeSeed({ expiresAt: past })
+    const { repo, store } = makeRepoStub({ seeds: [seed] })
+    const emit = jest.fn().mockResolvedValue(undefined)
+
+    const result = await executePendingActionCancel({
+      action: store.get('pa_1')!,
+      ctx: makeCancelCtx(),
+      repo,
+      emitEvent: emit,
+      now: REFERENCE_CLOCK,
+    })
+
+    expect(result.status).toBe('expired')
+    expect(store.get('pa_1')!.status).toBe('expired')
+    expect(emit).toHaveBeenCalledTimes(1)
+    const [emittedId, emittedPayload] = emit.mock.calls[0] as [
+      'ai.action.expired',
+      AiActionExpiredPayload,
+    ]
+    expect(emittedId).toBe(PENDING_ACTION_EXPIRED_EVENT_ID)
+    expect(emittedPayload.pendingActionId).toBe('pa_1')
+    expect(emittedPayload.resolvedByUserId).toBeNull()
+  })
+
+  // Scenario 5 --------------------------------------------------------------
+  it('scenario-5 stale-version single-record: re-check returns 412, row stays pending, no event emitted', async () => {
+    const seed = makeSeed({ recordVersion: 'v1' })
+    const { repo, store, setStatus } = makeRepoStub({ seeds: [seed] })
+    const emit = jest.fn().mockResolvedValue(undefined)
+
+    const staleTool = makeTool({
+      loadBeforeRecord: async () => ({
+        recordId: 'p-1',
+        entityType: 'product',
+        recordVersion: 'v2',
+        before: {},
+      }),
+    })
+
+    const recheck = await runPendingActionRechecks({
+      action: store.get('pa_1')!,
+      agent: makeAgent(),
+      tool: staleTool,
+      ctx: makeAuthCtx(),
+      now: REFERENCE_CLOCK,
+    })
+    expect(recheck.ok).toBe(false)
+    if (!recheck.ok) {
+      expect(recheck.status).toBe(412)
+      expect(recheck.code).toBe('stale_version')
+    }
+
+    expect(setStatus).not.toHaveBeenCalled()
+    expect(store.get('pa_1')!.status).toBe('pending')
+    expect(emit).not.toHaveBeenCalled()
+  })
+
+  // Scenario 6 --------------------------------------------------------------
+  it('scenario-6 stale-version batch partial: two rows live, one stale → failedRecords[] captured and confirm proceeds for survivors', async () => {
+    const records: AiPendingActionRecordDiff[] = [
+      {
+        recordId: 'r-1',
+        entityType: 'product',
+        label: 'Row 1',
+        fieldDiff: [],
+        recordVersion: 'v1',
+      },
+      {
+        recordId: 'r-2',
+        entityType: 'product',
+        label: 'Row 2',
+        fieldDiff: [],
+        recordVersion: 'v1',
+      },
+      {
+        recordId: 'r-3',
+        entityType: 'product',
+        label: 'Row 3',
+        fieldDiff: [],
+        recordVersion: 'v1',
+      },
+    ]
+    const seed = makeSeed({ records, recordVersion: null })
+    const { repo, store, setStatus } = makeRepoStub({ seeds: [seed] })
+    const emit = jest.fn().mockResolvedValue(undefined)
+
+    const bulkTool = makeTool({
+      name: 'catalog.bulk_update_products',
+      isBulk: true,
+      inputSchema: z.object({}).passthrough(),
+      loadBeforeRecords: async () => [
+        { recordId: 'r-1', entityType: 'product', label: 'Row 1', recordVersion: 'v1', before: {} },
+        { recordId: 'r-2', entityType: 'product', label: 'Row 2', recordVersion: 'v2', before: {} },
+        { recordId: 'r-3', entityType: 'product', label: 'Row 3', recordVersion: 'v1', before: {} },
+      ],
+      handler: async () => ({
+        recordId: 'batch-p',
+        commandName: 'catalog.bulk_update_products',
+      }),
+    })
+    const batchAgent = makeAgent({ allowedTools: ['catalog.bulk_update_products'] })
+
+    const recheck = await runPendingActionRechecks({
+      action: store.get('pa_1')!,
+      agent: batchAgent,
+      tool: bulkTool,
+      ctx: makeAuthCtx(),
+      now: REFERENCE_CLOCK,
+    })
+    expect(recheck.ok).toBe(true)
+    if (recheck.ok) {
+      expect(recheck.failedRecords).toHaveLength(1)
+      expect(recheck.failedRecords?.[0]).toMatchObject({
+        recordId: 'r-2',
+        error: { code: 'stale_version' },
+      })
+    }
+
+    const executed = await executePendingActionConfirm({
+      action: store.get('pa_1')!,
+      agent: batchAgent,
+      tool: bulkTool,
+      ctx: makeExecCtx(),
+      repo,
+      emitEvent: emit,
+      failedRecords: recheck.ok ? recheck.failedRecords ?? null : null,
+      now: REFERENCE_CLOCK,
+    })
+
+    expect(executed.ok).toBe(true)
+    expect(store.get('pa_1')!.status).toBe('confirmed')
+    expect(store.get('pa_1')!.failedRecords).toEqual([
+      {
+        recordId: 'r-2',
+        error: { code: 'stale_version', message: expect.any(String) },
+      },
+    ])
+    // First transition must carry the failedRecords onto the row.
+    const firstExtra = setStatus.mock.calls[0][3]
+    expect(firstExtra).toMatchObject({
+      failedRecords: [{ recordId: 'r-2', error: { code: 'stale_version' } }],
+    })
+    expect(emit).toHaveBeenCalledTimes(1)
+    const [, payload] = emit.mock.calls[0] as [
+      'ai.action.confirmed',
+      AiActionConfirmedPayload,
+    ]
+    expect(payload.executionResult).toMatchObject({ recordId: 'batch-p' })
+  })
+
+  // Scenario 7 --------------------------------------------------------------
+  it('scenario-7 stale-version batch all: every record stale → 412 stale_version, row stays pending', async () => {
+    const records: AiPendingActionRecordDiff[] = [
+      { recordId: 'r-1', entityType: 'product', label: 'Row 1', fieldDiff: [], recordVersion: 'v1' },
+      { recordId: 'r-2', entityType: 'product', label: 'Row 2', fieldDiff: [], recordVersion: 'v1' },
+    ]
+    const seed = makeSeed({ records, recordVersion: null })
+    const { store, setStatus } = makeRepoStub({ seeds: [seed] })
+
+    const bulkTool = makeTool({
+      name: 'catalog.bulk_update_products',
+      isBulk: true,
+      inputSchema: z.object({}).passthrough(),
+      loadBeforeRecords: async () => [
+        { recordId: 'r-1', entityType: 'product', label: 'Row 1', recordVersion: 'v9', before: {} },
+        { recordId: 'r-2', entityType: 'product', label: 'Row 2', recordVersion: 'v9', before: {} },
+      ],
+    })
+    const batchAgent = makeAgent({ allowedTools: ['catalog.bulk_update_products'] })
+
+    const recheck = await runPendingActionRechecks({
+      action: store.get('pa_1')!,
+      agent: batchAgent,
+      tool: bulkTool,
+      ctx: makeAuthCtx(),
+      now: REFERENCE_CLOCK,
+    })
+
+    expect(recheck.ok).toBe(false)
+    if (!recheck.ok) {
+      expect(recheck.status).toBe(412)
+      expect(recheck.code).toBe('stale_version')
+      expect(recheck.extra).toMatchObject({ staleRecords: ['r-1', 'r-2'] })
+    }
+    expect(setStatus).not.toHaveBeenCalled()
+    expect(store.get('pa_1')!.status).toBe('pending')
+  })
+
+  // Scenario 8 --------------------------------------------------------------
+  it('scenario-8 cross-tenant: tenant B cannot read tenant A row (returns null / never found)', async () => {
+    const seed = makeSeed({ tenantId: 'tenant-a', organizationId: 'org-a' })
+    const { repo, store } = makeRepoStub({ seeds: [seed] })
+
+    const rowAsA = await repo.getById('pa_1', {
+      tenantId: 'tenant-a',
+      organizationId: 'org-a',
+    })
+    const rowAsB = await repo.getById('pa_1', {
+      tenantId: 'tenant-b',
+      organizationId: 'org-b',
+    })
+
+    expect(rowAsA).toBeTruthy()
+    expect(rowAsB).toBeNull()
+    // The route returns 404 pending_action_not_found on null, and the row is
+    // never mutated by a cross-tenant caller.
+    expect(store.get('pa_1')!.status).toBe('pending')
+  })
+
+  // Scenario 9 --------------------------------------------------------------
+  it('scenario-9 idempotent double-confirm: second confirm returns prior executionResult without re-invoking handler or re-emitting event', async () => {
+    const seed = makeSeed()
+    const { repo, store } = makeRepoStub({ seeds: [seed] })
+    const emit = jest.fn().mockResolvedValue(undefined)
+    const handler = jest.fn().mockResolvedValue({
+      recordId: 'p-1',
+      commandName: 'catalog.product.update',
+    })
+    const tool = makeTool({ handler })
+
+    const first = await executePendingActionConfirm({
+      action: store.get('pa_1')!,
+      agent: makeAgent(),
+      tool,
+      ctx: makeExecCtx(),
+      repo,
+      emitEvent: emit,
+      now: REFERENCE_CLOCK,
+    })
+    expect(first.ok).toBe(true)
+    expect(handler).toHaveBeenCalledTimes(1)
+    expect(emit).toHaveBeenCalledTimes(1)
+
+    const emitAfterFirst = emit.mock.calls.length
+    const handlerAfterFirst = handler.mock.calls.length
+
+    const second = await executePendingActionConfirm({
+      action: store.get('pa_1')!,
+      agent: makeAgent(),
+      tool,
+      ctx: makeExecCtx(),
+      repo,
+      emitEvent: emit,
+      now: REFERENCE_CLOCK,
+    })
+
+    expect(second.ok).toBe(true)
+    expect(second.executionResult).toEqual(first.executionResult)
+    expect(handler.mock.calls.length).toBe(handlerAfterFirst)
+    expect(emit.mock.calls.length).toBe(emitAfterFirst)
+  })
+
+  // Scenario 10 -------------------------------------------------------------
+  it('scenario-10 idempotent double-cancel: second cancel returns same result without re-emitting event', async () => {
+    const seed = makeSeed()
+    const { repo, store } = makeRepoStub({ seeds: [seed] })
+    const emit = jest.fn().mockResolvedValue(undefined)
+
+    const first = await executePendingActionCancel({
+      action: store.get('pa_1')!,
+      ctx: makeCancelCtx(),
+      reason: 'nope',
+      repo,
+      emitEvent: emit,
+      now: REFERENCE_CLOCK,
+    })
+    expect(first.status).toBe('cancelled')
+    expect(emit).toHaveBeenCalledTimes(1)
+
+    const second = await executePendingActionCancel({
+      action: store.get('pa_1')!,
+      ctx: makeCancelCtx(),
+      repo,
+      emitEvent: emit,
+      now: REFERENCE_CLOCK,
+    })
+    expect(second.status).toBe('cancelled')
+    expect(emit).toHaveBeenCalledTimes(1)
+  })
+
+  // Scenario 11 -------------------------------------------------------------
+  it('scenario-11 read-only-agent refusal: effective mutationPolicy=read-only → recheck returns 403 read_only_agent, row stays pending', async () => {
+    const seed = makeSeed()
+    const { store, setStatus } = makeRepoStub({ seeds: [seed] })
+
+    // Sanity: policy resolver agrees the override collapses to read-only.
+    const effective = resolveEffectiveMutationPolicy(
+      'confirm-required',
+      'read-only',
+      'catalog.merchandising_assistant',
+    )
+    expect(effective).toBe('read-only')
+
+    const recheck = await runPendingActionRechecks({
+      action: store.get('pa_1')!,
+      agent: makeAgent({ mutationPolicy: 'confirm-required' }),
+      tool: makeTool(),
+      ctx: makeAuthCtx(),
+      now: REFERENCE_CLOCK,
+      mutationPolicyOverride: 'read-only',
+    })
+
+    expect(recheck.ok).toBe(false)
+    if (!recheck.ok) {
+      expect(recheck.status).toBe(403)
+      expect(recheck.code).toBe('read_only_agent')
+    }
+    expect(setStatus).not.toHaveBeenCalled()
+    expect(store.get('pa_1')!.status).toBe('pending')
+  })
+
+  // Scenario 12 -------------------------------------------------------------
+  it('scenario-12 prompt-override escalation refusal: overrides are additive-only, widen attempt is refused at confirm-time', async () => {
+    // The prompt-override merge layer (Step 5.3) is additive; it cannot grant
+    // the agent more mutation surface than its code declares. We prove the
+    // guarantee at the confirm layer by showing a read-only code declaration
+    // stays read-only regardless of the tenant override, and by showing
+    // `isMutationPolicyEscalation` would reject the escalation upstream.
+    const readOnlyAgent = makeAgent({
+      mutationPolicy: 'read-only',
+      allowedTools: ['catalog.update_product'],
+    })
+    const effective = resolveEffectiveMutationPolicy(
+      'read-only',
+      'confirm-required',
+      readOnlyAgent.id,
+    )
+    // Overrides never WIDEN — only narrow. Code-declared read-only sticks.
+    expect(effective).toBe('read-only')
+
+    const seed = makeSeed()
+    const { store, setStatus } = makeRepoStub({ seeds: [seed] })
+
+    const recheck = await runPendingActionRechecks({
+      action: store.get('pa_1')!,
+      agent: readOnlyAgent,
+      tool: makeTool(),
+      ctx: makeAuthCtx(),
+      now: REFERENCE_CLOCK,
+      // Even when the DB carries the "escalated" override, the resolver
+      // clamps it back to read-only, and the re-check returns 403.
+      mutationPolicyOverride: 'confirm-required',
+    })
+    expect(recheck.ok).toBe(false)
+    if (!recheck.ok) {
+      expect(recheck.status).toBe(403)
+      expect(recheck.code).toBe('read_only_agent')
+    }
+    expect(setStatus).not.toHaveBeenCalled()
+    expect(store.get('pa_1')!.status).toBe('pending')
+  })
+
+  // Scenario 13 -------------------------------------------------------------
+  it('scenario-13 reconnect: GET path re-hydrates the row by id between propose and confirm, then confirm proceeds normally', async () => {
+    const seed = makeSeed()
+    const { repo, store } = makeRepoStub({ seeds: [seed] })
+    const emit = jest.fn().mockResolvedValue(undefined)
+
+    // Simulate the client (mutation-preview-card) polling /actions/:id.
+    const reconnectRead = await repo.getById('pa_1', {
+      tenantId: 'tenant-a',
+      organizationId: 'org-a',
+    })
+    expect(reconnectRead).toBeTruthy()
+    expect(reconnectRead!.status).toBe('pending')
+
+    // Operator presses Confirm on the rehydrated card.
+    const executed = await executePendingActionConfirm({
+      action: reconnectRead!,
+      agent: makeAgent(),
+      tool: makeTool(),
+      ctx: makeExecCtx(),
+      repo,
+      emitEvent: emit,
+      now: REFERENCE_CLOCK,
+    })
+    expect(executed.ok).toBe(true)
+    expect(store.get('pa_1')!.status).toBe('confirmed')
+
+    // After confirm, a second poll yields the terminal row. The polling hook
+    // would stop scheduling further refreshes at this point.
+    const terminalRead = await repo.getById('pa_1', {
+      tenantId: 'tenant-a',
+      organizationId: 'org-a',
+    })
+    expect(terminalRead!.status).toBe('confirmed')
+    expect(terminalRead!.executionResult).toMatchObject({ recordId: 'p-1' })
+  })
+
+  // Scenario 14 -------------------------------------------------------------
+  it('scenario-14 illegal state transitions: direct pending→executing throws AiPendingActionStateError; executing→cancelled throws', async () => {
+    const seed = makeSeed()
+    const { repo } = makeRepoStub({ seeds: [seed] })
+
+    await expect(
+      repo.setStatus(
+        'pa_1',
+        'executing',
+        { tenantId: 'tenant-a', organizationId: 'org-a' },
+        { now: REFERENCE_CLOCK },
+      ),
+    ).rejects.toBeInstanceOf(AiPendingActionStateError)
+
+    // Walk to executing via the legal path (pending → confirmed → executing).
+    await repo.setStatus(
+      'pa_1',
+      'confirmed',
+      { tenantId: 'tenant-a', organizationId: 'org-a' },
+      { now: REFERENCE_CLOCK },
+    )
+    await repo.setStatus(
+      'pa_1',
+      'executing',
+      { tenantId: 'tenant-a', organizationId: 'org-a' },
+      { now: REFERENCE_CLOCK },
+    )
+
+    // Illegal: executing → cancelled is not in the allow-list.
+    await expect(
+      repo.setStatus(
+        'pa_1',
+        'cancelled',
+        { tenantId: 'tenant-a', organizationId: 'org-a' },
+        { now: REFERENCE_CLOCK },
+      ),
+    ).rejects.toBeInstanceOf(AiPendingActionStateError)
+  })
+
+  // Scenario 15 -------------------------------------------------------------
+  it('scenario-15 attachment cross-tenant: attachmentIds from another tenant → 403 attachment_cross_tenant, row stays pending', async () => {
+    const seed = makeSeed({ attachmentIds: ['att-foreign'] })
+    const { store, setStatus } = makeRepoStub({ seeds: [seed] })
+
+    // `findWithDecryption` is mocked at module scope to return an attachment
+    // row whose `tenantId` belongs to a different tenant. The recheck's
+    // cross-tenant guard inspects that field and short-circuits with 403.
+    const em = {} as unknown as import('@mikro-orm/postgresql').EntityManager
+
+    const recheck = await runPendingActionRechecks({
+      action: store.get('pa_1')!,
+      agent: makeAgent(),
+      tool: makeTool(),
+      ctx: { ...makeAuthCtx(), em, container: makeContainer() },
+      now: REFERENCE_CLOCK,
+    })
+
+    expect(recheck.ok).toBe(false)
+    if (!recheck.ok) {
+      expect(recheck.status).toBe(403)
+      expect(recheck.code).toBe('attachment_cross_tenant')
+    }
+    expect(setStatus).not.toHaveBeenCalled()
+    expect(store.get('pa_1')!.status).toBe('pending')
+  })
+
+  // Additional event-shape assertion ---------------------------------------
+  it('typed event helper: confirm / cancel / expired payloads carry resolvedByUserId per contract', async () => {
+    const seedA = makeSeed({ id: 'pa_a' })
+    const seedB = makeSeed({
+      id: 'pa_b',
+      expiresAt: new Date(REFERENCE_CLOCK.getTime() - 1000),
+    })
+    const seedC = makeSeed({ id: 'pa_c' })
+    const { repo, store } = makeRepoStub({ seeds: [seedA, seedB, seedC] })
+
+    const confirmEmit = jest.fn().mockResolvedValue(undefined)
+    await executePendingActionConfirm({
+      action: store.get('pa_a')!,
+      agent: makeAgent(),
+      tool: makeTool(),
+      ctx: makeExecCtx(),
+      repo,
+      emitEvent: confirmEmit,
+      now: REFERENCE_CLOCK,
+    })
+    const confirmPayload = confirmEmit.mock.calls[0][1] as AiActionConfirmedPayload
+    expect(confirmPayload.resolvedByUserId).toBe('user-a')
+
+    const expiredEmit = jest.fn().mockResolvedValue(undefined)
+    await executePendingActionCancel({
+      action: store.get('pa_b')!,
+      ctx: makeCancelCtx(),
+      repo,
+      emitEvent: expiredEmit,
+      now: REFERENCE_CLOCK,
+    })
+    const expiredPayload = expiredEmit.mock.calls[0][1] as AiActionExpiredPayload
+    expect(expiredPayload.resolvedByUserId).toBeNull()
+
+    const cancelEmit = jest.fn().mockResolvedValue(undefined)
+    await executePendingActionCancel({
+      action: store.get('pa_c')!,
+      ctx: makeCancelCtx(),
+      reason: 'user wants to stop',
+      repo,
+      emitEvent: cancelEmit,
+      now: REFERENCE_CLOCK,
+    })
+    const cancelPayload = cancelEmit.mock.calls[0][1] as AiActionCancelledPayload
+    expect(cancelPayload.resolvedByUserId).toBe('user-a')
+    expect(cancelPayload.reason).toBe('user wants to stop')
+  })
+})
+
+const EXPECTED_TOOL_HANDLER_CONTEXT_KEYS: ReadonlyArray<keyof McpToolContext> = [
+  'tenantId',
+  'organizationId',
+  'userId',
+  'container',
+  'userFeatures',
+  'isSuperAdmin',
+]
+
+describe('Pending-action executor tool-handler context shape', () => {
+  it('tool handler receives the full McpToolContext surface expected by downstream tools', async () => {
+    const seed = makeSeed()
+    const { repo, store } = makeRepoStub({ seeds: [seed] })
+    const emit = jest.fn().mockResolvedValue(undefined)
+    const received: McpToolContext[] = []
+    const tool = makeTool({
+      handler: async (_input, context) => {
+        received.push(context)
+        return { recordId: 'p-1' }
+      },
+    })
+
+    await executePendingActionConfirm({
+      action: store.get('pa_1')!,
+      agent: makeAgent(),
+      tool,
+      ctx: makeExecCtx(),
+      repo,
+      emitEvent: emit,
+      now: REFERENCE_CLOCK,
+    })
+
+    expect(received).toHaveLength(1)
+    for (const key of EXPECTED_TOOL_HANDLER_CONTEXT_KEYS) {
+      expect(received[0]).toHaveProperty(key as string)
+    }
+  })
+})