feat(ai-operator): task admission route, Delegate to Operator action, Playwright approve-after-browser-close (W08 of #5205)

[ToddHebebrand]

Closes #5246

Wave W08 (P3-1f) of #5205: the write that starts an AI Operator task, the action that fires it, and the browser proof that a delegated task outlives the session that created it.

What this adds

1. POST /api/v1/ai/operator/tasks (spec §12) — the only route that creates a task.

• Body is .strict(): a request carrying task, policySnapshot or approval is rejected outright. Requests cannot supply a principal, policy, or approval result.
• RBAC ai_agents:write plus the same MFA step-up the agent-run trigger uses.
• Server-side: resolves the device, checks org + site access (404 on a cross-org or site-restricted device — never a 403 that confirms existence), recomputes recipe availability from the two flags (422 with an actionable reason), enforces the pending-task cap (429), then calls W06's admitServiceRecoveryTask with the requester's authorized ceiling.
• 202 { taskId } once the task and its outbox row commit — Redis being down does not fail admission.
• Duplicate clientIdempotencyKey returns the existing task id. Implemented as ON CONFLICT DO NOTHING on the partial unique index plus a read-back, not a caught 23505: a unique violation aborts the surrounding transaction, so the read-back could not run inside it.

2. "Delegate to Operator" on the device page and on alert detail.

• Confirm dialog: recipe fixed to service recovery, service name required (prefilled from the alert where extractable), org/device read-only.
• Posts through runAction; on 202 navigates to /operator/tasks/<id>.
• Renders null entirely unless the aiOperatorTasks runtime flag is on. The alert variant targets the alert's own org, never the globally selected one (spec §5.1).
• The idempotency key is minted once per opened dialog and kept stable across retries of that dialog, so a double-click dedupes into one task server-side.
• data-testid="delegate-to-operator" / delegate-to-operator-confirm.

3. Playwright: ai-operator-approve-after-browser-close.spec.ts (acceptance scenario 3, spec §7.1 "authority across time"). Page Objects in pages/OperatorTaskPage.ts, data-testid selectors only.

4. docker-compose.yml + .env.example: both flags mapped explicitly and documented, default off (decision D2 — internal/test orgs only). Compose interpolates only what the environment: block names, so without the mapping the feature could not be switched on in any deployment and GET /config would report it disabled with no error anywhere.

What the Playwright spec actually proves, and what it does not

Real, driven through the browser: the button, the dialog, the admission POST (202 + the server's task id), the navigation to the task detail page and its render, an idempotent replay of the identical request resolving to the same task with no second row, the destruction of the creating browser context, a second independent login, and a real WebAuthn approve ceremony clicked in the approvals inbox — followed by a DB assertion that the task-linked intent settled approved.

Seeded, with the reason stated in the fixture header: the pending intent/approval the task waits on. Producing it for real needs a live LLM run (the investigate run must propose the restart and call createActionIntent) plus a coordinator tick. The e2e stack has neither. That transition is proven against real Postgres by aiOperatorServiceRecoveryE2E.integration.test.ts (W06). The task itself is never seeded — it must come from the real button, or the spec fails.

Contract I could not satisfy: the brief asks the flow to reach completed + verified_resolved with exactly one operation row. It cannot, honestly. That tail needs a connected agent to execute the restart and an independent device read to verify it; the e2e stack runs no agent — tests/script-cancel.spec.ts records the same limit in its own words ("the command this creates is never delivered and its device_commands row stays pending forever"). Faking the device from outside the API process would have proved nothing about W08. The execute→verify→document tail is covered by the W06 integration suite; this spec covers the session boundary that suite structurally cannot.

Two stack prerequisites these WebAuthn specs have are now documented in e2e-tests/README.md: PUBLIC_APP_URL must match the browser origin (the RP ID check fails otherwise, and it fails only these specs), and the enrolment ceremony rotates the refresh token, burning the session it runs in — hence exportCredentials/importCredentials in e2e-tests/webauthn.ts to carry the enrolled key from one context to the next. Approver-device registration has been grant-gated since #2707, so the helper mints a registerGrantId first; without one the options route answers 403 register_step_up_required.

Known gap, not fixed here (recorded per the brief)

deadline_at is enforced only inside advanceTask, which a paused task never re-enters — so a paused task does not expire on its own. The pause/resume/stop routes and that decision belong to P3-5.

Verification

All run locally on this branch after merging origin/main (3e56e27).

apps/api  npx vitest run src/routes/aiOperatorTasks.test.ts src/routes/config.test.ts \
                         src/db/autoMigrate.test.ts src/db/migrationRlsScope.test.ts
          → 4 files, 158 tests passed

apps/web  npx vitest run src/components/aiOperator src/stores/featuresStore.test.ts \
                         src/lib/__tests__/no-silent-mutations.test.ts \
                         src/lib/routeScope.test.ts src/lib/i18n
          → 15 files, 514 tests passed

apps/api  npx vitest run --config vitest.integration.config.ts \
            src/__tests__/integration/aiOperatorAdmission.integration.test.ts \
            src/__tests__/integration/rls-coverage \
            src/__tests__/integration/tenantCascade \
            src/__tests__/integration/tenant-export-policy
          → 7 files, 56 tests passed   (live Postgres)

apps/api  tsc --noEmit   → clean
apps/web  tsc --noEmit   → clean

scripts/check-migration-naming.sh --against-ref origin/main → OK

e2e-tests playwright test tests/ai-operator-approve-after-browser-close.spec.ts
          → 1 passed (16.5s), against a live worktree stack. Run three times
            in a row, green each time (the fixture cleans up its own prior
            rows, so it is genuinely rerunnable rather than one-shot).

The integration suite covers cross-org and site-restricted device → 404, flags off → 422, cap → 429, duplicate key → same id, the task row and outbox row present after 202, and a forged task field rejected.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YGPxXGTWpJKUNbEdR3TZEL

[cloudflare-workers-and-pages]

Deploying breeze with    Cloudflare Pages

Latest commit:	510bc88
Status:	✅  Deploy successful!
Preview URL:	https://a16c8a25.breeze-9te.pages.dev
Branch Preview URL:	https://feature-5205-ai-operator-wav-nzxz.breeze-9te.pages.dev

View logs

[ToddHebebrand]

PR review summary — /pr-review-toolkit:review-pr

Three specialist reviewers ran against gh pr diff 5272 (code-reviewer, silent-failure-hunter, pr-test-analyzer). Three findings, all fixed inline in 510bc88 — nothing deferred.

Fixed

1. HIGH (silent-failure-hunter) — a broken invariant was being reported as the caller's mistake, with no breadcrumb.
taskService.ts — the ON CONFLICT DO NOTHING read-back miss returned refusal: 'invalid_input', which the route turns into a 422 that reads to a technician as "your service name was wrong". Nothing in a caller's request can produce it (the index and the read-back are both org+key scoped), so it is a genuine consistency break — a concurrent erasure racing admission, or a future change desynchronising the index from the lookup — and it was landing in no log and no Sentry event. Now throws, matching operationService.ts's dispatch-claim cardinality check, so it surfaces as a 500 the top-level handler records. The caller-supplied key is deliberately not logged.

2. IMPORTANT (pr-test-analyzer) — the alert call site had no guard on which org it targets.
AlertDetailPage.tsx passes orgId={alert.orgId} precisely because spec §5.1 requires that changing the global org context while drafting cannot retarget the task. Nothing tested it: swapping it for useOrgStore's selected org would compile, pass every existing test, and aim a live remediation action at the wrong tenant. Added AlertDetailPage.delegateToOperator.test.tsx (5 tests) with the org store seeded to a deliberately different id, plus the status gating (rendered for active/acknowledged, hidden for resolved/dismissed).
Red-first verified, not assumed — reverting the wiring to the store value fails with:

AssertionError: expected 'org-globally-selected-9999' to be 'org-alert-owner-1111'

3. Lint (CI) — // eslint-disable-next-line react-hooks/exhaustive-deps was itself the lint error; that rule is not registered in this repo's config. Removed, reason kept as a plain comment.

Accepted as-is, with reasons

• code-reviewer: no findings. It independently verified the RBAC→MFA ordering against the POST /ai/agents/:id/runs precedent, the cross-org 404-not-403 behaviour under real RLS, the partial-index conflict target repeating its WHERE predicate (the 42P10 trap), the NOT IN cap predicate expanding correctly in drizzle 0.45.2, the .strict() rejections, the runAction catch pattern, and the export-policy registration for the new column.
• Soft cap race (code-reviewer, below its own confidence bar): the pending-cap count and the insert are separate round-trips, so a concurrent burst could land a few tasks past 100. Left alone deliberately — it is a user-recoverable 429 usage limit, not a tenancy or security invariant, and spec §7.2 asks for "a visible capacity result when full", not exact enforcement.
• Agent-selection tie-break untested (pr-test-analyzer, rating 4): org-owned before partner-wide, then oldest-first. Real but low-value to pin now; it affects which of several enabled agents runs, not tenancy.
• No standalone validator test for createOperatorTaskSchema (rating 3): its behaviour is covered through the route's HTTP-level it.each and again against live Postgres. Matches the file's existing convention.

Noted as genuinely strong

Both reviewers that looked for vacuous assertions found none in the places this repo has been burned before. The idempotent-replay tests assert row counts after the replay, not just replayed: true; the concurrent-POST test proves the database constraint serialises the race rather than app-level dedup; the cross-org 404 is asserted against a real device in a real second org under breeze_app; the migration's partial-index shape is asserted directly against pg_indexes; and the Playwright spec checks state, client_idempotency_key, requester_user_id and the approval→intent linkage in Postgres rather than trusting a success toast.

Verification after the fixes

aiOperatorTasks.test.ts 42 ✓ · AlertDetailPage* 14 ✓ · aiOperatorAdmission.integration.test.ts 17 ✓ (live PG) · tsc --noEmit clean in both apps · pnpm lint clean · migration-naming guard OK.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YGPxXGTWpJKUNbEdR3TZEL