feat(e2e+docs): Playwright web E2E green, security scan, core docs

- e2e: playwright config orchestrating mock-coasty + backend (test key,
  in-memory DB) + built web app; 3 passing web flows: full delegate->watch->
  approve->complete with live screen frames + cost summary; workflow builder->
  validate->run->approve->output; server-side BUDGET_EXCEEDED enforcement.
  Runtime security watcher asserts no sk-coasty-*/whsec_* in any browser request.
- desktop spec ready (runs once apps/desktop lands)
- backend: REST events polling fallback for mobile (/events.json?after=)
- mock: unauthenticated /health for orchestration probes; tolerant empty-JSON parser
- web: vite host pinned to 127.0.0.1 (IPv6 localhost broke readiness probes)
- docs: README (10-min offline quickstart + cost warnings), ARCHITECTURE,
  SECURITY (threat table), DEPLOYMENT, COOKBOOK (10 recipes)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: PrateekJannu

ARCHITECTURE.md

@@ -0,0 +1,203 @@
+# ARCHITECTURE
+
+How open-cowork is put together, and why. Companion docs: `DECISIONS.md`
+(choices + trade-offs), `SECURITY.md` (trust boundaries), `PLAN.md` (original
+build plan and package contracts).
+
+## The two hard truths the design hangs on
+
+**1. Local vs remote execution.** Only the desktop app can capture and control
+the user's *own* screen; web and mobile drive a Coasty cloud machine instead.
+This is modeled as one `Executor` interface with three implementations behind a
+single shared agent loop — the rest of the product never cares which screen it
+is driving.
+
+**2. The API key never touches a client.** All clients speak to the
+open-cowork backend, which is the only holder of `COASTY_API_KEY` and of every
+per-run `webhook_secret`. Clients hold short-lived session tokens.
+
+## Component map
+
+```text
+                       ┌────────────────────────────────────────────┐
+                       │                 Coasty API                  │
+                       │  /predict /sessions /runs /workflows        │
+                       │  /machines  · SSE events · HMAC webhooks    │
+                       └────────▲───────────────────────┬───────────┘
+                                │ X-API-Key (backend only)│ webhooks (HMAC)
+┌──────────────┐       ┌────────┴───────────────────────▼───────────┐
+│ apps/desktop │ IPC   │              apps/backend (Fastify)         │
+│  Electron    ├──────►│  auth (bearer tokens) · Coasty proxy        │
+│  main proc:  │ local │  estimates + confirmCostCents + budget caps │
+│  LocalRun-   │ runs  │  Ingestor: Coasty SSE → events table → bus  │
+│  Manager     │ mirror│  webhook receiver (verify before mutate)    │
+│  + Local-    │       │  SQLite (node:sqlite) · SSE fan-out         │
+│  Executor    │       └────────▲───────────────▲────────────────────┘
+└──────▲───────┘                │ REST + SSE     │ REST + polling
+       │ hosts                  │                │
+┌──────┴───────┐        ┌───────┴──────┐  ┌──────┴───────┐
+│ webview:     │        │  apps/web    │  │ apps/mobile  │
+│ the same SPA │        │  Vite+React  │  │ Expo / RN    │
+└──────────────┘        └──────────────┘  └──────────────┘
+         shared: packages/core · packages/executor · packages/ui
+```
+
+## packages/core — the framework-agnostic heart
+
+Zero runtime dependencies, isomorphic (Node + browser): injectable `fetch`,
+Web Crypto for HMAC, injectable clocks/sleeps for deterministic tests.
+
+- **`CoastyClient`** — typed methods for every documented endpoint. Transport
+  policy: timeouts compose with caller signals; retries use exponential backoff
+  with full jitter and honor `Retry-After`; **GET/DELETE retry by default, POST
+  retries only when an `Idempotency-Key` was provided** (a retried unkeyed POST
+  could double-bill). Errors map to `CoastyApiError` carrying `code`,
+  `request_id`, and code-specific extras.
+- **`runAgentLoop`** — screenshot → predict → execute → repeat until
+  done/fail/cap/abort. Takes an `AgentScreen` (what executors implement) and a
+  `PredictStepFn`, so predictions can come from a raw Coasty session *or* the
+  backend proxy. Emits structured events; tolerates up to 3 consecutive
+  action-execution failures; cooperative cancellation via `AbortSignal`.
+- **Workflow DSL** — validator enforcing every documented limit (≤200 steps,
+  ≤8 nesting, ≤16 parallel branches, retry 1–20, no approvals inside parallel,
+  reserved `save_as` names), the 13-op condition evaluator, `{{path}}`
+  templating, and a deterministic executor with `budget_cents` /
+  `max_iterations` / `deadline_seconds` guards — used for builder feedback,
+  dry-run estimates, and cross-checking the server.
+- **Cost estimator** — mirrors the documented pricing table exactly (including
+  the strict HD boundary: 1280×720 is *not* HD) and computes run/workflow
+  worst-case estimates the backend uses for the confirmation handshake.
+- **Webhook HMAC** — sign/verify `t=<unix>,v1=<hex>` over `"<t>.<body>"`,
+  constant-time byte comparison, ±300s tolerance both directions, multiple
+  `v1` entries accepted (rotation).
+- **SSE** — a spec-correct parser plus reconnecting event streams that resume
+  via `Last-Event-ID` with overlap de-duplication.
+
+## packages/executor — one loop, three screens
+
+```ts
+interface Executor extends AgentScreen {
+  kind: 'local' | 'remote-machine' | 'browser';
+  screenshot(): Promise<{ base64; width; height }>;
+  execute(action: CuaAction): Promise<void>;
+  dimensions(): Promise<{ width; height }>;
+  dispose(): Promise<void>;
+}
+```
+
+- **RemoteMachineExecutor** maps canonical actions onto the documented machine
+  endpoints (`GET /machines/{id}/screenshot`, `POST /machines/{id}/actions`)
+  through an injected transport — `CoastyClient` on the backend, a thin proxy
+  client elsewhere. `wait` sleeps locally; `raw` code execution is refused by
+  policy on every target.
+- **LocalExecutor** wraps a `NativeBridge` and solves the #1 documented
+  pitfall — coordinate scaling — by mapping model-space (screenshot pixels) to
+  input-space (real screen pixels) on every action.
+- **Bridges**: Windows is the reference — a persistent PowerShell daemon
+  (`System.Drawing` capture + `user32` SendInput-family input) speaking
+  JSON-lines over stdio, started via `-EncodedCommand`; zero native npm
+  modules, so installs never compile anything. macOS (`screencapture`/
+  `cliclick`/`osascript`) and Linux (`import`/`xdotool`) are best-effort
+  equivalents behind the same interface.
+- Actions are normalized first (`normalizeAction`) because the upstream docs'
+  reference table and examples disagree on some param shapes — both are
+  accepted, one canonical shape is executed.
+
+## apps/backend — proxy, custodian, fan-out
+
+- **Auth**: `POST /api/auth/login {email}` issues an opaque random token
+  (stored hashed, 7-day expiry). Single-tenant demo auth by design
+  (`DECISIONS.md` D6); every table already carries `user_id`.
+- **Spend safety — the confirmCostCents handshake.** Billable routes compute
+  the relevant number server-side (run worst case = `maxSteps × perStep`;
+  machines = first-hour rate; workflows = the budget cap itself) and reject
+  unless the client echoes it exactly (`409 ESTIMATE_CHANGED` with the expected
+  value). Budgets are then enforced again: runs whose worst case exceeds the
+  user's cap are refused with a suggested `maxSteps`; workflow runs pass
+  `budget_cents` so *Coasty* halts them at the cap (`GUARD_EXCEEDED`); wallet
+  pre-flight checks surface 402s before anything starts.
+- **Event pipeline.** Creating a run starts an **Ingestor** subscription to
+  Coasty's SSE stream (resuming from the last stored seq). Events are mirrored
+  into the `events` table **keeping the upstream `seq`**, applied to run state,
+  and published on an in-process bus. Client SSE routes replay from SQLite
+  (`Last-Event-ID`), then attach to the bus — with gap-filling if live events
+  race the replay. The same table serves cloud runs, local runs, workflow
+  runs, and per-user notification feeds (`stream_kind` + `stream_id`).
+- **Webhooks as reconciliation.** `POST /webhooks/coasty` verifies the HMAC
+  against the per-run secret (looked up by the payload's run id) over the
+  exact raw bytes before *any* state change; stale/tampered/unknown deliveries
+  get 401. Verified events update run state and post to the owner's
+  notification stream — so terminal transitions arrive even if an SSE
+  subscription dropped. `GET /api/runs/:id` additionally reconciles
+  non-terminal runs against Coasty on read.
+- **Local runs.** The desktop app mirrors its LocalExecutor loop through
+  `POST /api/local-runs(/:id/events)`, so a run on your laptop is supervisable
+  from your phone exactly like a cloud run — same timeline route, same
+  approval notifications.
+- **Persistence**: `node:sqlite` behind a repository class (`db.ts`); events
+  have `(stream_kind, stream_id, seq)` primary keys so ingestion is idempotent
+  and replay is a range scan. Postgres is a contained swap (`DEPLOYMENT.md`).
+
+## Realtime model (end to end)
+
+```text
+Coasty SSE ──► Ingestor ──► events table (durable, seq) ──► bus ──► client SSE
+Coasty webhooks ──► HMAC verify ──► state + notification stream ──► bus ──► feeds
+desktop local loop ──► POST /api/local-runs/:id/events ──► same table/bus
+```
+
+Every hop resumes: the Ingestor reconnects to Coasty with `Last-Event-ID`;
+clients reconnect to the backend the same way; mobile polls
+`/api/runs/:id/events.json?after=N` (React Native fetch lacks streaming).
+Nothing is lost or duplicated because the durable seq is the single cursor.
+
+## apps/desktop — local control, safely
+
+Electron with `contextIsolation: true`, `nodeIntegration: false`. The renderer
+is the same SPA as the web app; a small preload exposes
+`window.cowork = { platform, backendUrl, startLocalRun, cancelLocalRun }`.
+`LocalRunManager` (main process) runs core's `runAgentLoop` with
+`LocalExecutor`, gets predictions through the backend's `/api/proxy/sessions`
+(key stays server-side), and mirrors events to `/api/local-runs` in batches.
+The E2E suite deliberately never starts a local run (it would seize the real
+mouse); that path is covered by unit tests plus an opt-in native capture smoke
+test (`COWORK_NATIVE_SMOKE=1`).
+
+## apps/web + packages/ui
+
+One Vite SPA serves browsers and the desktop webview. `packages/ui` is a
+dependency-free design system (dark-first tokens, accessible primitives,
+domain components like `EventTimeline`, `ScreenView`, `ApprovalBar`,
+`WorkflowStepTree`); apps map API DTOs into its presentational props. The live
+screen view polls machine screenshots every 2s while a run is active — frames
+are cross-platform and cheap (`DECISIONS.md` A3).
+
+## apps/mobile
+
+Expo/React Native with zero extra native deps; every screen is
+react-native-web-compatible, which is how the same UI is verified in CI
+(D7). Timelines poll the REST fallback; approvals hit the same resume routes.
+
+## tools/mock-coasty
+
+A faithful offline twin of the documented API: key kinds + billing headers,
+the full error catalog, exact pricing math, run/workflow steppers with the
+documented state machine, durable SSE with replay, HMAC-signed webhook
+delivery, sandbox machines with generated-PNG screenshots. Deliberately does
+**not** import `core` (D9) so contract bugs can't hide; behavior triggers in
+task text (`NEEDS_HUMAN`, `MUST_FAIL`, `RUN_LONG`, `MOCK_DONE`) make every
+lifecycle deterministic for tests and demos.
+
+## Data model (SQLite)
+
+```text
+users(id, email, budget_cents, created_at)
+sessions(token_hash PK, user_id, expires_at)            -- tokens stored hashed
+runs(id, user_id, kind coasty|local, coasty_run_id, machine_id, task, status,
+     cua_version, max_steps, budget_cents, cost_cents, steps_completed,
+     result_json, error_json, awaiting_human_reason, webhook_secret, …)
+workflow_runs(id, user_id, coasty_workflow_run_id, workflow_id, status,
+     budget_cents, spent_cents, awaiting_step_id, webhook_secret, …)
+events(stream_kind, stream_id, seq, type, data_json, created_at,
+       PRIMARY KEY (stream_kind, stream_id, seq))       -- the realtime spine
+```

COOKBOOK.md

@@ -0,0 +1,160 @@
+# COOKBOOK
+
+Recipes for common open-cowork jobs. All of them work against the mock server
+(`pnpm dev:mock`) with zero spend — add ` NEEDS_HUMAN `, ` MUST_FAIL `, or
+` RUN_LONG ` to any task text to script the mock's behavior deterministically.
+
+---
+
+## 1. Run a task on a cloud machine and approve it from your phone
+
+1. **Laptop (web)**: Machines → *Provision machine* (Linux, confirm the
+   $0.05/hr rate) → Delegate → "Download the invoices NEEDS_HUMAN and file
+   them" → confirm the worst-case cost → the run starts.
+2. **Phone (mobile app)**: sign in with the same email. The Runs tab shows the
+   run; when it pauses, the *"A run needs your approval"* banner appears.
+3. Open it → read the pause reason and the event timeline → add a note →
+   **Approve**. The laptop's live view resumes within a second (SSE), and the
+   run finishes with a cost summary on both devices.
+
+Why it works: the backend mirrors every event into a durable per-run stream
+and pushes an `awaiting_human` notification onto your per-user feed; both
+clients are just subscribers (see `ARCHITECTURE.md` → Realtime model).
+
+## 2. Let the agent drive *your own* computer (desktop)
+
+1. Run the stack (`pnpm dev:mock` + `dev:backend` + `dev:web`), then
+   `pnpm dev:desktop`.
+2. In the desktop window, the Delegate screen's machine list has **"This
+   computer (local screen)"** as the first target. Pick it, describe the task,
+   and read the confirmation — it means it: the agent moves your real mouse.
+3. Watch the timeline; cancel anytime from the desktop, the web app, or your
+   phone (local runs are mirrored like cloud runs).
+
+Notes: Windows needs nothing extra (PowerShell bridge). macOS: grant Screen
+Recording + Accessibility. Tip: keep tasks narrow and use approval-style
+wording; the loop aborts after 3 consecutive failed actions.
+
+## 3. Build a workflow with a human gate (and a hard budget)
+
+Workflows → *New workflow*. The prefilled template is exactly this recipe:
+
+```json
+{
+  "steps": [
+    { "id": "fetch",  "type": "task", "task": "Open order {{inputs.order_id}} and read the invoice total", "save_as": "invoice" },
+    { "id": "check",  "type": "assert", "condition": { "op": "truthy", "value": "{{invoice.passed}}" }, "message": "Could not read the invoice" },
+    { "id": "gate",   "type": "human_approval", "message": "Approve publishing the result?" },
+    { "id": "ok",     "type": "succeed", "output": { "total": "{{invoice.result}}" } }
+  ]
+}
+```
+
+*Validate + estimate* gives instant local validation (every documented DSL
+limit) plus typical/worst-case cost. Save, then *Run workflow*: pick a
+machine, set the **budget cap** — that number is the `budget_cents` guard
+Coasty enforces server-side; breaching it stops the run with
+`GUARD_EXCEEDED`. Approve the gate when it pauses; the output panel shows the
+templated result.
+
+## 4. Retry flaky steps automatically
+
+Wrap the fragile part in a `retry` and assert on the bound result:
+
+```json
+{ "id": "r", "type": "retry", "max_attempts": 3, "body": [
+  { "id": "submit", "type": "task", "task": "Submit the expense form", "save_as": "out" },
+  { "id": "verify", "type": "assert", "condition": { "op": "truthy", "value": "{{out.passed}}" } }
+]}
+```
+
+(Mock tip: a task containing `MUST_FAIL_ONCE` fails the first attempt and
+succeeds on the second — handy for demos.)
+
+## 5. Fan out across parallel branches
+
+```json
+{ "id": "p", "type": "parallel", "branches": [
+  [ { "id": "a", "type": "task", "task": "Export the sales report", "save_as": "sales" } ],
+  [ { "id": "b", "type": "task", "task": "Export the support report", "save_as": "support" } ]
+]},
+{ "id": "both", "type": "assert", "condition": { "op": "and", "conditions": [
+  { "op": "truthy", "value": "{{sales.passed}}" },
+  { "op": "truthy", "value": "{{support.passed}}" }
+]}}
+```
+
+Branches run concurrently and bind results under their `save_as` names.
+Remember the documented limits: ≤16 branches, and no
+`human_approval`/`succeed`/`fail` inside a branch.
+
+## 6. Bound machine spend with TTLs
+
+When provisioning, set *Auto-terminate after N minutes* — that is the
+documented `ttl_minutes` (5 min–7 days): the VM terminates itself and all
+billing stops, even if everyone forgets it. Stopped machines bill $0.01/hr
+(storage); terminate to reach $0.
+
+## 7. Use the agent loop programmatically (no UI)
+
+```ts
+import { CoastyClient, runAgentLoop } from '@open-cowork/core';
+import { RemoteMachineExecutor } from '@open-cowork/executor';
+
+const coasty = new CoastyClient({
+  baseUrl: process.env.COASTY_BASE_URL!,   // mock or real — same code
+  apiKey: process.env.COASTY_API_KEY!,     // server-side only!
+});
+const { machine } = await coasty.createMachine({ display_name: 'script-vm' });
+const session = await coasty.createSession({ screen_width: 1280, screen_height: 720 });
+const executor = new RemoteMachineExecutor({ machineId: machine.id, transport: coasty });
+
+const outcome = await runAgentLoop({
+  screen: executor,
+  task: 'Open the settings page and enable dark mode',
+  maxSteps: 15,
+  predictStep: (input) =>
+    coasty.sessionPredict(session.session_id, {
+      screenshot: input.screenshotB64,
+      instruction: input.instruction,
+    }),
+});
+console.log(outcome.status, outcome.stepsUsed, `${outcome.totalCostCents}¢`);
+await coasty.deleteSession(session.session_id);   // free the concurrency slot
+```
+
+## 8. Verify your webhook receiver with signed test vectors
+
+```ts
+import { signWebhookPayload, verifyWebhookSignature } from '@open-cowork/core';
+
+const body = JSON.stringify({ event: 'run.succeeded', run: { id: 'run_1' } });
+const header = await signWebhookPayload({ secret: 'whsec_yours', body });
+const verdict = await verifyWebhookSignature({ body, header, secret: 'whsec_yours' });
+// verdict.valid === true; tamper with `body` and it flips with reason 'bad_signature'
+```
+
+## 9. Estimate costs before committing to anything
+
+```ts
+import { runEstimateCents, workflowEstimateCents, formatCents } from '@open-cowork/core';
+
+runEstimateCents({ cuaVersion: 'v3', maxSteps: 40 });    // { perStep: 5, min: 5, max: 200 }
+workflowEstimateCents(definition);                        // { typicalCents, worstCaseCents }
+formatCents(125);                                         // "$1.25"
+```
+
+The backend exposes the same math at `POST /api/estimate` — the UI's numbers
+and the enforcement numbers can never drift apart.
+
+## 10. Script the mock for demos and tests
+
+```ts
+import { createMockCoasty } from '@open-cowork/mock-coasty';
+
+const { app, state } = createMockCoasty({ tickMs: 50, walletCents: 200 });
+await app.listen({ port: 4010 });
+// task text drives behavior: NEEDS_HUMAN pauses, MUST_FAIL fails verification,
+// RUN_LONG takes 20 steps, MOCK_DONE finishes a predict immediately.
+// state.webhookDeliveries / state.events let tests assert everything.
+```