📄 raw markdown for agents/LLMs: /CLAUDE.md · all docs

Bluebut — developer guide

⛔ NEVER EVER DO THIS — couple logic to the presentation layer instead of the data model

A separation-of-concerns / layering violation: control flow must depend on the stable data contract (the model/state), never on the rendered output meant for humans (display strings).

Sub-names, same root:

• Programming against the view, not the model — reading what the page renders instead of the state it renders from.
• Stringly-typed control flow — branching on free-form text where a typed enum/flag was available.
• Depending on an incidental, unstable representation — display copy carries no stability contract; it can change any release. Building logic on it = relying on a non-guarantee.

This repo's positive form is the truth ladder: read the source of truth — cookie/jar → inlined Relay state → persisted GraphQL doc_id — and treat the rendered DOM as the last resort. Matching localized innerText (e.g. "Tillåt alla cookies") is the bottom rung dressed up as a check. Correct example: detect FB's cookie banner via the server-rendered flag "shouldShowCookieBanner":true, not the button's label. Skills: surface-extract, local-browser.

Operationally this means: new extraction adapters are WIRE-BASED GraphQL replay, and the legacy DOM scrapers are a migration backlog. See ⭐ Extraction doctrine under Adapters.

Facebook outreach operator dashboard for the Bofrid housing-acquisition funnel. Groups are the primary object today, but the spine (jobs, accounts, data planes) is site- and object-agnostic — a page, a person, any object on any site rides the same machinery.

Four pages: Groups (home, / → /groups) + Jobs, Accounts, Tools. Opening a group is a full-page workspace (/groups/<id>[/<tab>], pages/groups/GroupWorkspace.tsx), tabs Overview + People (admins). Posting is not a tab — broadcasting is a cross-group batch from the Groups-index checkbox panel.

Architecture — the mental model

One object, one verb, one log. The operator works on objects (groups today); every action is a job; every job's trail lands in HyperDX + the durable job ledger, keyed by job_id. None of it is FB- or group-specific.

🚧 ARCHITECTURE IN MIGRATION — chromebox → cloakbox consumer

Bluebut is being migrated from owning a browser fleet (the chromebox + its own fingerprint/proxy/session/HAR/tap stack) to being a CONSUMER of the cloakbox identity platform (gologin/pbox), which owns all of that. Bluebut then owns ONLY its FB domain verbs. The target architecture, remove-list, and current status are inlined below.

⛔ TRANSPORT — consume cloak-cdp over its HTTP API, NOT the MCP

The platform is reached over two surfaces — keyvault (pick accounts) and cloak-cdp (launch + drive). For everything bluebut runs unattended (the runner bin/bluebut-adapter.mjs, the bridge, bin/* scripts, cron), cloak-cdp is consumed over its plain HTTP API, NOT the MCP JSON-RPC endpoint. The MCP (.../mcp) is for interactive agent sessions; it can be absent/interactively-authed in headless/cron runs (the exact failure the harness warns about) — so runtime code MUST use the HTTP API.

• Base: https://cloak-cdp.hostbun.cc · auth: ?key=ddash or header X-Api-Key: ddash (env CLOAK_API_KEY).
• POST /api/call body {"tool":"<name>","args":{…}} → {"result":…} — the one call for every verb (cdp_load/cdp_save/cdp_catalog/cdp_drive/wiretap_*).
• GET /api/tools (full input schemas) · GET /api/launchable (= cdp_catalog; ?service=facebook&runnable=1&summary=1) · GET /api/health.
• GET /api/tools (full input schemas) · GET /api/launchable (= cdp_catalog) · GET /api/health (liveness). Quick check: curl -s 'https://cloak-cdp.hostbun.cc/api/health?key=ddash'.
• Seam: adapters/_lib/cloak-client.js — the ONE client, and it speaks POST /api/call (stateless, no handshake). Every verb (cdpLoad/cdpSave/cdpCatalog/cdpDrive/wiretap*) goes through its callTool. Nothing else calls the platform directly; never re-introduce the MCP JSON-RPC transport.

Status (2026-07-09): CUT OVER (code) — the runner is cloakbox-only. The BLUEBUT_CLOAKBOX gate is GONE: bin/bluebut-adapter.mjs always cdp_loads → drives → cdp_saves; the chromebox (fb.chrome.blpk.cc) is retired at the deploy level. Live catalog: run=5 · mint-new=300 · birth=0 — only 5 accounts have a Windows cloakbox device; the other 300 need a device minted (per-account human VNC login via add-account). Remaining violations to migrate off: the runner still runs its OWN capture stack (netcapture/har/gql-tap/graphql-store → own MinIO + bofrid.dev) — the platform wiretap already captures everything (bluebut-wiretap consumes it). CAPTURE = platform; RECOGNIZE (*-wire.js) = bluebut.

⛔ NO CLOAKBOX DEVICE → NO JOB (for that account, for ANY verb)

Every job runs through cdp_load(service, slug), and cdp_load can only load an account that has a Windows cloakbox device (cdp_catalog verdict run). An account with only a mac/linux device or none (verdict mint-new/birth) has nothing to load — the job dies at cdp_load with "no seeded device for facebook/ … nothing to load." This is not scrape-specific: it is true for read, scrape, post, admin, messenger — every verb. So "can this account run" is exactly "does it have a cloakbox device", nothing else (not logged_in, not membership, not admin-ness).

Live reality: only 5 of 305 facebook accounts are runnable (run=5 · mint-new=300). joel-skola, philip, pojtie are among them; most named + all df-* farm accounts are NOT. To make one runnable, MINT a device (cdp_new → human VNC login → cdp_save) via the add-account skill.

Enforced in code — never pick a non-runnable actor. The cloakbox-runnable set is getCloakboxCatalog() → makeDrivable(sessions, cloak) (ui/src/lib/util.tsx); drivable(slug) is the hard gate. Every place that chooses WHICH account drives a job filters to drivable FIRST and returns null / [] when none qualifies — the action is then DISABLED (with the "mint a device" hint), never fired as a doomed job:

• GroupWorkspace.pickActor() — refresh / scrape / admin-edit actor (drivable is the filter, scoring only orders survivors).
• broadcastActor.candidatesForGroup() + makeAutoActor fallback — the broadcast WHO-posts router (hard-filtered, no non-drivable tail).

The trap this closes: stale fb_account_group edges for purged Page pointers (uthyra-se, bofrid, …) — Pages that were never cloakbox accounts (the pointer-model purge removed the kv rows but left the membership edges). A blind memberAccts[0] pick floated one of these first → cdp_load facebook/uthyra-se → dead. drivable excludes them because they have no device. (Cleaning the ghost edges is DB hygiene, separate from the gate.)

Execution path — UI → job → bridge → runner → box

operator click
 → useJobs().runJob / startJob   (ui/src/state/jobs.tsx)  — UI job: in-memory + toast + HyperDX
   → runCli / runCliLive         (ui/src/api/index.ts)    — threads job_id
     → POST /exec/stream (SSE)    (ui/bridge/opencli-bridge.mjs, VITE_BRIDGE_URL)
       → spawn runner             (bin/bluebut-adapter.mjs, env BLUEBUT_JOB_ID)
         → import adapters/<site>/<cmd>.js
           → cloak-client POST /api/call {tool:cdp_load,args:{slug}} → resolvePageWs
             → cloakserve (Windows seed browser on pbox, platform-gated) → Facebook
             → POST /api/call {tool:cdp_save} at the end

The runner is cloakbox-only (the BLUEBUT_CLOAKBOX gate is gone): every FB job calls the platform's cdp_load over the HTTP API (POST /api/call, key ddash — see the transport banner above) which resolves+egress-verifies the proxy, gates the fingerprint, and injects the session, then cdp_saves at the end — and SKIPS the retired chromebox-only proxy-gate/hardenSession/egress-guard/ensureFbSession (the platform owns them). adapters/_lib/cloak-client.js is the ONE seam; adapters are unchanged.

Three data planes

Under cloakbox: keyvault stays the account store but the platform owns identity writes (cdp_save); the Traffic firehose + HAR planes are RETIRED (platform wiretap captures every seed).

bofrid.dev is read-only EXCEPT the deliberate write tables: the traffic firehose (har_recording/traffic_entry/fb_traffic_live) and the fb-bot scraped-posts feed (fb_scraped_posts). Everything else on bofrid.dev (DMs, broadcasts) stays read-only. The heavy traffic index lives on bofrid.dev, not hostbun, to keep the shared operational DB lean — traffic-store.js creds() resolves BOFRID_SUPA_URL first.

Dev principles

1. One object, one verb, one log. Object = the thing (group/page/person/account); job = every action; HyperDX + job ledger = the trail (keyed by job_id).
2. Every action is a job. Observability is built in — the job ships steps + screenshot-on-fail + one copy-log button. Debug by checking the job first.
3. Agnostic by default. A job links to what it acted on via the generic (site, target_type, target_id) triple — never a site-/object-specific column. New object or site = no schema change.
4. Self-heal over diagnose-then-act. One smart verb that figures out what's needed beats N manual verbs. ensureFbSession heals cold sessions mid-action. Expose manual rungs as escape-hatches, never the default.
5. Never trust a click — re-read the authoritative end-state. Mutating adapters re-open the menu / reload /people/ and only return ok once the state actually flipped (okWith/failWith). Optimistic UI lies.
6. One source of truth per plane. Accounts → keyvault. Live entity state + job ledger → bluebut-db (via bluebut-rest; cutover off hostbun db.hostbun.cc DONE/LIVE). Traffic firehose (traffic_entry/har_recording/fb_traffic_live) + scraped-feed → bofrid.dev (R/W). Legacy history (DMs/broadcasts) → bofrid.dev (read-only). HAR blobs → bluebut-minio har bucket. Writing the wrong plane is a bug.
7. The accounts are the asset. Anti-detect rules are enforced in code, not convention. Survival beats throughput.
8. Adapters are first-class repo code. Owned in adapters/, picked up on next run — no install/symlink. Fork upstream fixes down; don't edit toolbox up.
9. Fail loud with forensics. failWith() attaches a screenshot + selector strategies tried. Swallow errors only where a comment says it's deliberate.
10. Precise terminology. cookie ⊂ storage_state ⊂ session.
11. Keep the gate green. npm run check (lint + typecheck + build + test) on every push. Errors block.
12. Run long-running scripts in a subagent, not the main loop. Any script that occupies the session — the group-creation queue, the login-box flow, a long scrape/batch — launch it via the Agent tool (background or foreground subagent) so the main agent stays free to monitor and inspect the running job (tail logs, check the job ledger / HyperDX, answer questions) instead of being blocked waiting on it. The subagent owns the script's lifecycle; the main agent observes. Don't Bash-block the main loop on a script that runs for minutes.

Running locally

npm install      # repo root — @jackwener/opencli (lib) + runner
cd ui && npm install
cd .. && npm run bridge   # terminal 1 — local adapter bridge (BRIDGE_PORT, .env → :8790)
cd ui && npm run dev      # terminal 2 — http://localhost:5173

⛔ LOCAL-FIRST — verify locally, DON'T push to test

git push deploys to PROD (Coolify auto-deploys @main). It is NOT a test button. The bridge + adapters + UI are all local code — the same files prod runs — so every change is observable on your machine in seconds. A push is the LAST step, once the change is proven locally, not a way to see whether it works. Don't burn a prod deploy per edit.

The loop is .env-wired end-to-end: BRIDGE_PORT=8790 + VITE_BRIDGE_URL=http://localhost:8790 (headroom squats the 8787 default, so we run on 8790), so a locally-running UI drives the locally-running bridge — same code path as prod. Test recipe by what you touched:

Changed	See it without deploying
bridge (ui/bridge/*)	restart npm run bridge (no HMR; ~1s boot). curl localhost:8790/health
listing text / compose (_lib/listing-post-text.js + /listings/compose)	curl -s localhost:8790/listings/ads?limit=1 → pipe one row into POST /listings/compose → read the text. No FB post, no browser.
adapter (adapters/**)	picked up on the NEXT runner spawn — no restart. Run it: node bin/bluebut-adapter.mjs adapters/facebook/<cmd>.js --account joel-skola …
messenger ingest (daemon→bridge handleE2eeIngest)	the whatsmeow daemon is PROD-only and POSTs to the PROD bridge, so a local daemon can't drive it. Test the bridge's persistence by POSTing a sample DecryptedMessage to the LOCAL bridge: curl -X POST -H "authorization: Bearer $BRIDGE_INGEST_TOKEN" localhost:8790/messenger/e2ee/ingest -d '{"messages":[{"account":"pojtie","thread_key":"<peer_fbid>","message_id":"local-1","sender_id":"<peer>","timestamp_ms":<now>,"message_type":"image","text":"","is_self":false,"attachments":[{"attachment_type":"image","mimetype":"image/jpeg"}]}]}' → it writes the SAME bluebut-db (local bridge reads the prod DSN), so check fb_message/fb_message_attachment/fb_thread/fb_contact. NO prod deploy, no live send.
UI (ui/src/*)	Vite HMR — already live on :5173, no restart
pure logic (_lib/*)	npm test (node --test) — a sibling *.test.mjs is faster than any endpoint

Push only a change that (a) is verified locally and (b) is actually meant for prod. Then follow the global "verify after deploy" rule. If a change is bridge/adapter/UI-only, the local run IS the proof — the deploy just ships it.

Onboarding new accounts

Cloakbox is the only onboarding path. New account = the add-account skill — creds+proxy→keyvault, cdp_new mint device, cdp_save GROUPED before login, HUMAN VNC login, cdp_save session. NEVER login.py/Mac. Proxy assignment: npm run proxy:pick -- --account <a> --geo SE (proxyless accounts self-provision via _lib/proxybun.js). Known: capsolver self-hosted down → hand-solve captcha. (The old Mac-local login path — local-dev/, login-container/, npm run local* — is DELETED.)

Without the bridge, action buttons fail; read-only pages still work. Single root .env (Vite reads via envDir: ".."; bridge/runner/sniffer/canary/hyperdx all read it):

VITE_SUPABASE_URL=https://bluebut-rest.blpk.cc  # entity graph + job ledger (self-owned bluebut-db via PostgREST)
VITE_SUPABASE_KEY=<service_role_jwt>          # UI-ONLY (baked into the browser bundle at build). Server-side (runner/bridge/canaries) reads this JWT from KEYVAULT — `bluebut/config/rest-service-key` — not env.
VITE_BOFRID_SUPA_URL=https://supabase.bofrid.dev
VITE_BOFRID_SUPA_KEY=<service_role_jwt>
VITE_CHROMEBOX_URL=https://fb.chrome.blpk.cc  # box: CDP gateway + /chrome/* + /accounts/*
VITE_BRIDGE_URL=http://localhost:8790         # local opencli bridge (8790: headroom squats the 8787 default)

# self-owned data plane (Coolify; cutover DONE — entity graph on bluebut-rest, HAR on MinIO)
S3_ENDPOINT=http://minio-malct88jd5gp0miiag4jhslm:9000  # bluebut-minio; HAR blobs → `har` bucket
S3_ACCESS_KEY=<minio_root_user>               # also MINIO_ROOT_USER / MINIO_ROOT_PASSWORD
S3_SECRET_KEY=<minio_root_password>
# BLUEBUT_HAR_BUCKET=har                       # default

Deployment & infrastructure — Coolify (hostbun)

Everything runs on the hostbun Coolify (coolify.hostbun.cc, MCP coolify-hostbun), project bluebutchromebox / env production (environment_id=21), one server: funnelsites-bluebut-hexabyte-chrm = Hexabyte e3, 194.104.94.173, Traefik proxy on docker network coolify. (NOT hetzner — that old bluebut app is a stale dupe.) Apps auto-deploy from devdashco/bluebut@main on push; one push redeploys UI + bridge together.

⛔ WORK ON main — NO FEATURE BRANCHES

Coolify deploys bluebut@main, so main IS the deploy branch. Commit straight to main and push — do NOT open a feature branch or a PR for normal work. Keep the gate green (npm run check) before every push; a green push deploys. (The one exception is a genuinely risky, long-lived change the operator explicitly asks to stage off-main — otherwise always main.)

Apps (project bluebutchromebox)

Data planes — the self-owned move (cutover DONE)

bluebut has moved off the shared hostbun Supabase → its own private Postgres + MinIO in the Coolify project:

Migration status: DONE / LIVE. Entity graph + job ledger served by bluebut-db via bluebut-rest.blpk.cc; HAR on MinIO; chromebox_sessions retired (keyvault sole account store). bofrid.dev unchanged — traffic firehose + scraped-feed (R/W) and legacy DMs/broadcasts (read-only) stay there.

Secrets are not in this file — S3_*, BRIDGE_TOKEN, JWT/service-role keys, DB passwords live in keyvault + the Coolify app env (*** masked). Internal DSN hosts are the Coolify resource UUIDs, reachable only on the coolify docker network. Observability → shared hyperdx-v2 (otel.hyperdx.hostbun.cc, ServiceName='bluebut'/'chromebox-traffic').

Tech stack

• React + Vite + TypeScript; TanStack Query.

• Use the component library — never hand-roll UI primitives. (1) app primitives in ui/src/components/Ui.tsx (Button, Input, Select, Card, Row, …) — Ui.tsx IS the primitive layer, the only file allowed to render the raw elements; (2) MUI v9 (themed dark, ui/src/theme.ts) for everything else. The lookup table:

  Need	Use	Never
  modal	<Dialog>	a position:fixed; inset:0 backdrop div, raw <dialog>
  side panel	<Drawer anchor="right">	a bespoke slide-over
  menu / popover	<Menu> / <Popover>	an absolutely-positioned div
  dropdown	<TextField select> + <MenuItem> (slotProps={{ select: { displayEmpty: true } }} when the empty option is the placeholder)	a raw <select> + inline style
  tabular list	<AppDataGrid> (MUI X DataGrid)	a raw <table>
  clickable list rows	<List> / <ListItemButton selected>	styled <button> cards
  error / warning box	<Alert> + <AlertTitle>	a red-bordered div
  loading placeholder	<Skeleton>	a gradient div
  small status pill	<Chip size="small">	a styled <span>
  text / layout	<Typography> / <Box> / <Stack> on theme colors	<div style={{ color: "#9ca3af" }}>

  (MUI v9 gotchas: paper styling is slotProps={{ paper: { sx } }}; system props are gone off Typography/Stack — put fontWeight/alignItems/flexWrap in sx.)

  Enforced, not merely documented: ui/eslint.config.js no-restricted-syntax makes a hand-rolled backdrop, a raw <dialog>, a raw <select> and a raw <table> a CI error naming the replacement. Ui.tsx is exempt (it's the primitive). The ~11 legacy sites carry a line-scoped eslint-disable-next-line … -- legacy raw <select>/<table>: migrate to … — that comment IS the migration backlog; delete it by migrating, never copy it into new code.

• Color = design tokens, NEVER raw hex. ONE semantic palette is the source of truth: the CSS @theme block in ui/src/index.css (--color-bg/-surface/-fg/-muted/-faint/-line/-primary/-info(-fg/-bg)/-success(-strong/-fg/-bg)/-warning(-fg/-bg)/-danger(-strong/-fg/-bg)/-violet(-fg/-bg)/-hover) with its JS mirror in ui/src/tokens.ts (import t where a real color is needed — the MUI theme.ts, canvas/SVG-attr colors). Reference var(--color-<role>) in every inline style/sx and Tailwind utility; a hex literal in a component is drift (there were ~950 of them across 4 grays-for-one-role etc — collapsed to the token set). One role → one value, everywhere. Keep index.css @theme and tokens.ts paired.

• Frontend/UI polish → the impeccable skill. Any design/redesign/critique/audit of a UI surface — visual hierarchy, spacing, typography, color, motion, accessibility, empty/error states, responsive behavior — invoke /impeccable first. It governs how UI work is shaped here; the component-library table above is the primitive floor, impeccable is the taste layer on top.

• No routing library — a tiny History-API router (ui/src/lib/router.ts). Route /<page>[/<sub>]; navigate with navigate(page, sub?). Refresh/deep-link safe.

Conventions

Session terminology (use these exact words)

cookie  ⊂  storage state (storage_state)  ⊂  session (the account record)
c_user      { cookies[], origins[] }           { storage_state, fb_id, status, proxy, … }

• cookie — ONE FB name=value pair (c_user, xs, datr, i_user).
• storage state (storage_state) — the auth bundle = cookies + localStorage origins (Playwright/CDP shape). The precise name for what we inject/dump/persist. Prefer over "jar".
• session — the account record = storage_state + identity (fb_id, display_name) + status + proxy + metadata. Contains a storage state.

jar survives only as casual shorthand + stable identifiers (decodeJar, jar-truth.js) — don't introduce it in new code.

Quality gate — npm run check

CI (.github/workflows/check.yml) runs it — plus the ui build — on every push to main + every PR. ERRORS block; WARNINGS tolerated. Coolify auto-deploys main independently, so CI is the TRIPWIRE (revert on a red ✗), not a deploy gate. Run npm run check locally before every push.

• npm run lint — root ESLint (Node: adapters/, bin/, ui/bridge/).
• npm run lint:ui — UI ESLint (TS-aware). lint:all = both.
• npm run typecheck — tsc -b in ui/. npm test — adapter unit tests (node --test adapters/_lib/*.test.mjs).
• Underscore prefix (_unused) marks an intentionally-unused var/arg/caught-error.

DB schema — NO ORM, NO migration tool (deliberate)

There is no Drizzle/Prisma/Kysely and no migration runner — and there shouldn't be. The DB is reached ONLY over PostgREST REST (_lib/db.js, UI dbGet), so an ORM's query layer would go unused; and the schema is self-extending at runtime (fb_schema_ingest RPC + ~77 ADD COLUMN IF NOT EXISTS), which a versioned-migration tool would fight. The three SCHEMA.sql files ARE the schema-as-code — idempotent (CREATE TABLE IF NOT EXISTS / ADD COLUMN IF NOT EXISTS), heavily commented, rebuildable; re-applying the whole file converges prod to the file. Apply them by hand via the bluebut-db MCP (or psql) — that is the "migration" step; there is no schema:apply script (running DDL from Node would need pg, an unwanted dep).

• npm run db:types — generate ui/src/api/db-types.gen.ts (one Db<Table> interface per bluebut-db table) from the LIVE PostgREST swagger, ZERO deps (just fetch, reads VITE_SUPABASE_URL/_KEY from .env). This is a drift-check reference for the hand-written runtime interfaces in api/index.ts (GroupPost, FeedPost, …) — NOT imported at runtime (several UI types are bridge/view SHAPES, not raw rows). Regenerate after a schema change and diff to catch a stale interface (the class of bug behind is_premium vs premium_listing_price_ore).

Jobs — every action is a job (the agnostic spine)

Every operator action runs as a job — the only way the UI calls an adapter. The job is the unit of work and observability; not tied to groups or FB.

Taxonomy — four layers (think Skyvern: WorkflowRun → Task → Step → Action)

Source of truth: adapters/_lib/taxonomy.js (LIFECYCLE/TERMINAL, ActionType, OPS with read/write per adapter, classify/rollup/opFor). UI re-declares the static enums in ui/src/lib/taxonomy.ts (no cross-boundary import); taxonomy.test.mjs guards drift. New automation → the new-automation skill.

• The Job is the unit — a chain of adapters is still ONE job with more steps.
• A Batch owns 1..N jobs and home for cross-target concerns (routing, jitter, cooldown, stop-on-block). Don't model a batch as a fake mega-job.
• A Step is a phase, not a second adapter call (that's a second Job in the same Batch).

The durable job ledger — object-agnostic (adapters/SCHEMA.sql)

One generic job table in the entity-graph DB (bluebut-db; site-agnostic schema at root; per-site tables in adapters/<site>/SCHEMA.sql). Durable record behind the bridge's wiped-on-restart in-memory list.

CREATE TABLE job (
  job_id text PRIMARY KEY,   -- BLUEBUT_JOB_ID (same id threaded to HyperDX)
  batch_id text, site text, cmd text NOT NULL, op text, access text, account text,
  target_type text,          -- 'group' | 'page' | 'person' | 'account' | null
  target_id text, target_url text, target_name text,
  status text NOT NULL,       -- running | ok | failed | partial | blocked | content_unavailable
  ok boolean, aborted_reason text, summary jsonb,
  har_key text,               -- bucket key of this job's full HAR: job/<job_id>.har.gz
  started_at timestamptz, ended_at timestamptz, duration_ms integer,
  created_at timestamptz DEFAULT now(), updated_at timestamptz DEFAULT now()
);
-- indexes: (target_type,target_id,created_at DESC), (created_at DESC), batch_id, (account,created_at DESC)

The link is the generic (target_type, target_id) pair. Any object's history = same store, no schema change: a group's jobs = target_type='group' AND target_id=<fb_group_id>; page/person/account analogous. site records which adapter family ran it.

• Write — the runner writes one row per run, best-effort: status=running on start, terminal state on end.
• Read — Q.jobsForTarget(type, id) (ui/src/lib/util.tsx); GroupJobs.tsx uses it. Point any new object-history surface at this query — never a per-object bespoke log.
• Still group-shaped, fix when extending: target resolution only maps --group/--page args → target_type (the map is [['group','group'],['page','page']]); account/person-scoped commands leave target_type=null. The terminal update only enriches from result.group_* and falls back to target_type='group'. Generalize both before relying on page/person history.

The model — ui/src/state/jobs.tsx

• runJob({ label, account, site, cmd, args, summarize }) — one-shot adapter call; auto status/toast/failure-log.
• startJob({ label, account, site, cmd }) → { event, succeed, warn, fail } — a multi-step flow the page drives (e.g. promote→verify→accept in util.tsx).
• Status: running | ok | warn | failed. warn = completed but not verified (invite sent, role unconfirmed) — distinct from ok (verified).

Observability is built in

• Every step + terminal state → HyperDX via shipLog (ui/src/logger.ts): [job:step|ok|warn|fail], tagged job_id, ServiceName='bluebut'.
• job_id threads UI → bridge → runner (BLUEBUT_JOB_ID), so the FB network trail (ServiceName='chromebox-traffic', source=runner) shares the id.
• On failure: a diagnostic (adapters/_lib/diagnostics.js failWith()) — screenshot + selector strategies. Rendered inline in the Jobs dock.
• One ⧉ copy log button per job (jobToText) → id + steps + diagnostic + ready-to-run HyperDX query.

Where jobs surface

• GlobalJobsDock (bottom-left, app-global, live; expand to watch its tab).
• Jobs page (/jobs) — history + inline live tab + bridge job list (fetchBridgeJobs).
• Live tab screencast — bridge relays box Chromium's Page.startScreencast over WS /screencast?account=X into a canvas (components/LiveScreen.tsx). Watching a job = watching the real anti-detect Chrome.

Rule for any new feature: run it through a job, ship steps by job_id, link via (target_type, target_id), attach a diagnostic on failure, expose copy-log.

Adapters — project-owned, run via the local runner

Everything an adapter needs lives in this repo — no install, no symlink, no global opencli:

bluebut/
  bin/bluebut-adapter.mjs   # the runner — argv → register → CDP → JSON. Its `finally`
                            #   is the post-job pipeline: stop capture → saveGraphqlCalls
                            #   → mineHar (atlas) → harvestEntities (PASSIVE WIRE) → buildHar
  adapters/
    SCHEMA.sql              # site-agnostic shared schema (the `job` ledger)
    _lib/                   # shared helpers — NO adapter is a "site"; everything cross-
                            #   adapter lives here, ESM, with a sibling <name>.test.mjs:
                            #     netcapture.js   — CDP capture (GraphQL bodies + WS frames)
                            #     fb-schema.js    — the ONE Relay decoder (parseGqlJson,
                            #                       extractInlinedBlobs, mineTypes/mineHar)
                            #     passive-wire.js — ambient harvester: WIRES registry +
                            #                       harvestEntities() (reuses fb-schema's decoder)
                            #     db.js           — the one PostgREST write client (auto-steps)
                            #     sessions.js · group-sync.js · taxonomy.js · diagnostics.js · …
    facebook/<cmd>.js       # one cli({...}) per file (active/pull adapters)
    facebook/SCHEMA.sql     # per-site FB entity tables (groups, people, members, …)
  messenger/                # the Messenger box (site:'messenger') — its OWN subsystem,
                            #   NOT under adapters/ (jobs/, lib/, decode.js, e2ee/)

Where new extraction code goes (by the two axes — see the Extraction doctrine):

• Active/pull read or write of ONE object → a new adapters/facebook/<cmd>.js (cli({...})), run as a job.
• Passive/ambient harvest that should ride EVERY job → a new entry in WIRES inside adapters/_lib/passive-wire.js ({ name, typenames, extract }) — never a new adapter, never a new folder. The runner already calls it.
• A new Relay-decode primitive (parsing, id reassembly, blob extraction) → adapters/_lib/fb-schema.js, so there stays exactly ONE decoder both the atlas miner and the passive wire share.
• Every _lib/ module gets a sibling *.test.mjs (run by npm test: node --test adapters/_lib/*.test.mjs messenger/lib/*.test.mjs). New entity tables / column ALTERs → the matching SCHEMA.sql (site-agnostic → root; FB entity tables → adapters/facebook/SCHEMA.sql).

opencli is a library (@jackwener/opencli/registry for cli({...}) + Strategy); the runner does dispatch + CDP lifecycle. Pinned to 1.7.8 (1.7.22+/1.8.x enforce access:'read'|'write' on every cli({...}) — a bounded future change).

⭐ Extraction doctrine — wire-based GraphQL replay is the DEFAULT; DOM scraping is DEPRECATED

This is the operational form of the truth-ladder rule at the top of this file. Any adapter that READS data from FB reads it off the same persisted-GraphQL wire the page itself reads — it does NOT scrape rendered HTML. DOM scraping (innerText / querySelector / role="article" / aria-* / matching localized labels) is the bottom rung: it breaks on every locale change and every FB UI refresh, fakes timestamps, and can't see hidden data (folders, real ids). New read adapters are wire-based, full stop. The legacy DOM read-scrapers are a migration backlog, not a template to copy.

Two axes: where the data lives × how we consume it

Axis A — the SOURCE (where a fact lives) has three answers. Axis B — the MODE (how an adapter gets it) has two.

Axis A — source (3, ranked by the truth ladder):

A wire = a structured source you read by typed field, not by label → GraphQL and Socket are wires; the DOM is not. "Wire-based" = read off a wire.

Axis B — consumption mode (2):

The passive wire — adapters/_lib/passive-wire.js (full playbook: the passive-wires skill). Every job buffers its GraphQL + inlined-Relay bodies in-process. harvestEntities(network, ctx) runs in the runner's finally (sibling to mineHar), walks every Relay record once, merge-upserts what it recognizes. ALWAYS-ON — harvest + every capture prerequisite default ON (opt-out !== '0': BLUEBUT_PASSIVE_WIRE/_CAPTURE_GQL_BODIES/_CAPTURE_PAGES/_WORKER_HTTP; WS tap always attaches), at BOTH sites (box runner finally + local rolling capture). Recognizers, three kinds: (1) __typename-routed entries in the WIRES registry; (2) __typename-less signature-detected handlers in collect() (Relay strips __typename off fragments — group-about-fragment, join-config, invite); (3) self-scoped freshenOwn* wires. Routed by __typename+numeric id+strong signature, never a DOM label.

⭐ THE FULL-OBJECT MANDATE — mirror FB's object into ours. When you wire an entity, harvest every field the node carries — the aim is to replicate FB's object in our DB; a field skipped now is an extra FB call (= detection risk) later. Discipline: (1) dump the whole node first and read its full key union before writing the extractor; (2) reassemble across fragments — match by signature field + numeric id, merge by id (never assume one node = the whole object); (3) structural fields only (privacy_info.icon_name), a display string only when FB exposes it nowhere else; (4) grow the schema to fit — ALTER … IF NOT EXISTS + NOTIFY pgrst (expected, not scope-creep); (5) reject phantoms — require a strong entity-only signal + a test; (6) prove it live against bluebut-db. Every wire change updates the docs in the same commit (this field list, the new-automation skill, a memory entry). The group wire is the reference.

• person → User nodes → fb_person (the ONE User/lead/actor hub, canonical on numeric fb_id; INSERT-new-only so a passing node never clobbers a richer scrape). fb_user + fb_profile were redundant second/third User tables — folded into fb_person + dropped 2026-07-08. See [[reference_fb_identity_model]].
• group → Group nodes → fb_group (the FULL about-object: name, member_count, privacy via privacy_info.icon_name, cover, has_membership_questions, description via description_with_entities, location + location_fb_id from group_locations[], created_time from group_history). FB spreads these across the header Group node AND __typename-less about-card fragments — a signature detector picks up the fragments, collect() reassembles by fb_group_id. Active twin = probeGroupWire (_lib/facebook.js, same inlined /about blobs + group_admin_profiles roster), called WIRE-FIRST by probeGroup (DOM drift-fallback only).
• page → Page nodes → ENRICH-ONLY fb_page (PATCH name/username matched by page_fb_id). A Page is its OWN typename, never folded into the fb_person User hub via the passive person wire (would poison it). NB: a Page CAN still legitimately appear IN fb_person as an ACTOR/lead when it POSTS (a company page posting a listing) or is a group member — fb_person is the actor hub, is_company distinguishes; the rule is only that the passive person/User wire must not create Page rows. A bare Page node in passing traffic doesn't carry the asset_id (page_key), so this wire can't INSERT — that's the managed-page wire's job (below). An account can act AS a page, so a Page's pic also feeds the avatar wire.
• managed-page → a ProfileSwitcherEligibleProfile node (FB inlines profile_switcher_eligible_profiles on ~every document) → INSERT fb_page + the fb_account_page account↔page link. The ONE node carrying delegate_page_id (= asset_id = page_key), the key a bare Page lacks — so unlike the enrich-only page wire it creates both rows. Requires delegate_page_id (→ a real managed page). Shares toPageRow with active list-pages (_lib/pages-wire.js); additive. Also denormalizes onto the account's KEYVAULT row (managed_pages = [{page_key, asset_id, page_fb_id, name, username}], via freshenManagedPages) so a downstream LOADER (fb-bot) can load an account → act AS a page without touching bluebut-db. bluebut-db fb_account_page = source of truth; keyvault.managed_pages = its loader-facing projection.
• post → group feed Story nodes → fb_post (merge-upsert on post_url) + poster promotion, via adapters/_lib/post-sync.js. Wire twin of the deprecated scrape-group: reads STRUCTURAL fields off the Story — numeric post_id (dedup key), permalink_url, epoch creation_time, owning User, body via a bounded comment-safe walk — off any job that loaded a group feed. Scoped to /groups/. Poster promotion = fb_person upserted on canonical fb_id + fb_person_signal 'posted' (same post-sync.js helper get-group-feed calls). Passive wire does NOT feed the bofrid.dev fb-bot pipeline (that's get-group-feed's deliberate write).
• comment → group-post Comment nodes → fb_comment (merge-upsert on comment_id=legacy_fbid) via post-sync.js extractStoryComment/persistComment. Reads STRUCTURAL fields: legacy_fbid (dedup), feedback.id, feedback.url (→ derives post_url+group_fb_id from the comment itself), body.text, epoch created_time, depth, author{id,name,url}, parent comment_direct_parent.legacy_fbid, reply count. Reactions COUNTS-ONLY (feedback.reactors.count+top_reactions) — no per-reactor table (paginated query = detection risk). Scoped to /groups/. fb_comment.post_url FKs fb_post → persistComment retries post_url=null on 23503. Comments ride the permalink document (inlined Shape B) / UFI XHR, NOT the feed wire; active twin get-post-comments (_lib/comment-wire.js, pure inlined read, no DOM click).
• message (LightSpeed twin — NOT a Relay WIRES entry) → Messenger fb_thread/fb_message/fb_contact/fb_thread_participant/fb_message_reaction via messenger/lib/passive-messages.js harvestMessages. Threads ride FB's LightSpeed step-VM payload (lightspeed_web_request), the SAME wire messenger/sync-inbox/sync-thread read. collectLsCalls gathers LS blobs from all three passive sources — /api/graphql responses, SSR-inlined initial sync (pages[].html), binary ws/lightspeed frames (lsPseudoCallsFromWs) — then runs the SAME extractPayloads→decodeCaptured→persistTables (ADDITIVE) path. E2EE caveat: thread_type=15 threads carry METADATA + the ENCRYPTED envelope, never a plaintext body — bodies come only from the bluebut-e2ee daemon. Gated BLUEBUT_PASSIVE_MESSAGES (default on); wired at all three harvest sites. is_self off readActingIdentity. Test: passive-messages.test.mjs.
• join-config → a group's JOIN-DIALOG node (GroupsCometRequestToParticipateOnJoinDialogQuery's group) → the join contract: fb_group flags (is_rules_agreement_enabled, has_email_verification_question, join_questionnaire, join_email_config) + fb_group_join_question + fb_group_rule, via join-config-wire.js extractJoinConfig + group-sync.js upsertGroupJoinConfig. Node is __typename-less → a STRONG signature detector (isJoinConfigNode: numeric id + community_participation_questions[] + is_rules_agreement_enabled) routes it in collect(). Additive-only (active get-group-join-config owns the authoritative replace). NB: FB's legacy has_membership_questions ≠ the modern community_participation_questions gate — this wire never writes has_membership_questions (the group wire owns it).
• notification → EVERY notifications-jewel notif → fb_notification (per-account: notif_type/actor_fb_id/target_id/body/seen_state/created_time). Signature-detected off the notif's tracking JSON blob (STRUCTURAL notif_type, never localized body). The jewel (CometNotificationsDropdownQuery) rides ~every job → comments/mentions/tags/friend-accepts self-harvest. The group-invite subset also lands in fb_group_invite. Additive; body display-only. Scoped to ctx.account.
• my-membership-edge → the VIEWER's own edge off a Group node carrying viewer_join_state and/or the per-node admin gates → is_member to fb_account_group (always safe, additive) + our role to fb_group_member (OUR fb_id, from readActingIdentity). Role is written ONLY when the reliable if_viewer_is_admin/if_viewer_is_not_admin gate is present (a group-page visit inlines it) — NEVER a guessed member, so a passing all_joined_groups node can't downgrade a known admin (the roster DELETE stays banned passively; get-user-groups owns the authoritative role split via the ADMIN_MODERATOR_GROUPS listType). So visiting any group we admin self-heals our admin edge.
• own-avatar → the account's own actor (User or acted-as Page) → if the scontent asset token changed, saveAvatarToStorage + repoint avatar_url in keyvault (token cached in avatar_src; matched by stored fb_id). Bytes → fb-media MinIO bucket (_lib/media-store.js), served via the bridge's public GET /media/fb-media/<key> (un-tokened, unlike /har/blob). avatar_url = ${BLUEBUT_MEDIA_BASE}/media/fb-media/avatars/<account>.<ext>.
• own-session → when FB server-asserted the account is live this job (sessionSaveDecision), re-dump the jar to keyvault — but ONLY under a 6-rung gate so it can never replace a working session with a broken one: (1) dumped jar logged-in (c_user≠0 + xs), (2) complete (datr present), (3) FB served an authenticated document (readActingIdentity non-zero USER_ID), (4) no integrity error (accessFromNetwork ∉ {checkpoint,blocked,auth} — a walled session still inlines a USER_ID, so the access verdict closes that hole), (5) same account (actingId===c_user), (6) xs rotated. Prior jar stashed to storage_state_prev; stamps storage_state_saved_at.
• Device bundle is NOT passive (deliberate). The full anti-detect profile — FB device tokens (datr = the ~2-year FB device id; sb/dbln/fr) + client fingerprint (UA/Client Hints, screen/DPR, hardwareConcurrency/deviceMemory, tz/locale, WebGL vendor+renderer, canvas/audio hash, platform, webdriver tell) — is captured ACTIVELY by persistDeviceProfile (_lib/device-profile.js) at login + load-session only, stored as device_profile+fb_device. Binding one stable profile per account is what stops the logouts. No passive device wire.
• Writes are additive merge-upserts (or enrich-only PATCH for pages) — never the destructive roster DELETE upsertMembers does (passive sees one node, not an authoritative set); role edges + account↔page links are deliberately NOT written passively. Everything best-effort; never touches the job result.
• Backlog (high-value, doc_id already known): the notifications jewel is the free-rider — CometNotificationsDropdownQuery (doc_id 27646303031640503), fired on ~every page, and get-user-groups already decodes group-admin invites off it (notif_type=group_invited_to_group → fb_group_invite). Add an invite/notification wire to WIRES that recognizes those story nodes passively, so admin/group invites self-refresh on any job instead of only when get-user-groups runs. (Future: a general fb_notification.)

The (active) wire pattern (copy from a reference impl, don't reinvent):

1. The cloakbox wiretap (the surface-extract skill — captures every seed's traffic incl. WS) on the target surface → its backing doc_id + variables + the response path (…edges[].node + page_info).
2. Author adapters/facebook/<cmd>.js with an in-page replay (pageExpr): read fb_dtsg/lsd/uid LIVE from the page, fetch('/api/graphql/', …) with that doc_id, page on end_cursor until has_next_page:false.
3. Extract by structural field name + stable enum key (viewer_join_state, tab_groups_list.edges) — NEVER a DOM label.
4. doc_id ROTATES → keep it in an env-overridable const and re-capture (cloakbox wiretap) when the query starts erroring; fail loud (failWith) with the doc_id in the message. See the doc_id lifecycle doctrine below for the exact discipline.

⭐ doc_id lifecycle — the discipline (enforced by eslint + skill fb-doc-id)

A doc_id is FB's persisted-query id: the server stores the query text; the client sends id + variables + fb_dtsg. How every FB read AND mutation is replayed. We handle it like the mature players — hardcoded constants, patched by hand, detected-on-failure.

1. Per-FB-build, NOT per-account. Same id for every account on the same FB release. Per-account/session = the tokens + variables (fb_dtsg/lsd, uid=c_user, vars), read LIVE off the page each run. Never store fb_dtsg.

2. Pin every doc_id in an ENV-OVERRIDABLE const keyed by FriendlyName (mirrors mautrix-meta's hand-patched {DocID, FriendlyName} map):

const DEMOTE_DOC = process.env.BLUEBUT_DEMOTE_ADMIN_DOC_ID || '27831756479762517'; // GroupsCometMembersRemoveAdminMutation

Env override = patch a rotated id without a rebuild. A bare inline doc_id literal is an eslint error — named const + env fallback + FriendlyName comment. Two flavors: doc_id (default) and client_doc_id (client-persisted, e.g. IG avatar); capture tells you which — don't assume.

3. The PAGE is the truth-source; a const can drift. doc_ids live in FB's JS bundles → discovery = load the page, capture the id (cloakbox wiretap). Rotation check = capture live, grep the FriendlyName, diff vs the const. Read the id live off the page instead of pinning when you can (the Messenger box does — zero hardcoded doc_id).

4. Rotation is DETECTED, never scheduled. A stale doc_id can't fake success — FB returns a loud PersistedQueryNotFound-class error (HTTP 400, or 200 + {"errors":[…]}), never silent wrong data (the whole reason wire > DOM). failWith() with the doc_id in the message; npm run canary:admin (cron) catches a rotation the day it ships. Re-capture, swap the const/env, done.

Reference implementations (read before writing a new extractor):

• list-joined-groups.js — joined groups (doc_id 9974006939348139). The wire replacement for list-groups.
• get-activity-log.js — paginated stories (doc_id 27054591887516604, category_key swapped — 134 categories one query).
• set-account-language.js — a mutation replay (doc_id 23915562351374516) — proof WRITES can be wire.
• create-group-post.js + _lib/create-post-wire.js — group-post mutation (ComposerStoryCreateMutation, doc_id 28568493719405999). Text (own + act-as-Page) fires the persisted mutation directly; the response hands back id+permalink (no feed re-scan). Act-as-Page is wire: identity rides the envelope as av===__user===input.actor_id===<page fb_id> signed by the manager's unchanged fb_dtsg (i_user-flipped session shares it). IMAGE posts still fall to the DOM composer. On success mirrors into fb_post (persistOwnPost, authored_by_us, numeric id + base64 story_gid).
• delete-group-post.js + _lib/delete-post-wire.js — DELETE twin (useCometFeedStoryDeleteMutation, doc_id 36213403264942057). ⚠ targets input.story_id=base64 story_gid, NOT numeric post_id (resolveStoryIdExpr reads it off the permalink's inlined Relay). Ownership-gated on fb_post.authored_by_us; re-reads to confirm gone; tombstones the row.
• The whole Messenger box (messenger/) — DMs off the LightSpeed wire.

External references (prior art, cloned in meta-reverse-engineered/): the "Reverse-Engineering Messenger" case study (intuitiveexplanations.com/tech/messenger — FB web request shape); raxod502/unzuckify (our session model: durable jar reused, fb_dtsg re-scraped live, login only on auth-fail; doc_id discovery by grepping the served JS for the FriendlyName — what bin/canary-doc-ids.mjs does); mautrix/meta (the Go client decode.js is ported from — hand-patched {DocID, FriendlyName} map).

Migration backlog — DOM read-scrapers → wire replay (each entry: don't reintroduce the DOM scraper):

• list-groups/list-member-groups/list-group-invites → DELETED — replaced by list-joined-groups + get-user-groups.
• sync-messages + adapters/facebook/send-message.js → DELETED — superseded by messenger/jobs/sync-inbox/send-message (LightSpeed wire).
• scrape-group → DELETED — replaced by get-group-feed (GroupsCometFeedRegularStoriesPaginationQuery; MANY groups per warm session via --groups; full structural post via post-sync.js → fb_post+fb_person+fb-bot feed). Passive post wire = ambient twin.
• scrape-new-members → WIRE — ActivitiesListPaginationQuery (doc_id 27418668794433773) + GroupsCometAdminActivityLogItemSeeDetailsDialogQuery (doc_id 37221570147456563) via _lib/member-request-wire.js. Full member object (fb_id, profile_url, account_created_at, city+city-page-id, education/work/about, membership+rules enums, questionnaire answers incl. email).
• scrape-profile → WIRE — inlined Relay (Shape B, _lib/profile-wire.js), User reassembled across fragments → identity + all public about fields/sections + timeline_context, stored in fb_person.profile_raw. Privacy-gated.
• list-friends → WIRE — inlined viewer.all_friends (Shape B) off /friends/list. Fail-loud if it overflows the inlined page and the pagination doc_id is unset.
• list-friend-requests → WIRE — incoming = inlined viewer.friend_requests; outgoing = FriendingCometOutgoingRequestsDialogQuery (doc_id 9355113201284242).
• get-group/ingest-groups/sync-new-groups (shared probeGroup) → WIRE — probeGroupWire (_lib/facebook.js) reads the about-object off inlined /about + the group_admin_profiles roster on /members/admins; wire-first, DOM drift-fallback only. LIST enumeration also WIRE via shared enumerateJoinedGroups (_lib/joined-groups-wire.js, GroupsCometAllJoinedGroupsSectionPaginationQuery doc_id 9974006939348139, paged to exhaustion). Prune-safety requires enumeration.complete.
• list-pages → WIRE — inlined actor.profile_switcher_eligible_profiles.nodes[].profile (Shape B, _lib/pages-wire.js): Page fb_id/name/pic/delegate_page_id/is_profile_plus. GOTCHA: read LIVE DOM <script data-sjs> (a bg fetch() returns a stripped shell), walk depth ≥60.
• get-page-insights — still DOM, NOT a doc_id case: Business Suite streams figures over the DataGateway WebSocket (gateway.facebook.com/ws/streamcontroller) as a subscription (useMAIBAAsyncMessageSubscription, doc_id 27434986989461233). Wire migration = a DGW-subscription decoder (future).

Mutations — wire replay by default; no DOM fallback (rotation fails loud, caught by npm run canary:doc-ids). Rule #5 binds: never trust the send; re-read the end-state. DONE wire-only (doc_ids): create-group-post (ComposerStoryCreateMutation), create-group (useGroupsCometCreateMutation 37309644325300927), invite-to-group (useGroupsCometInviteLinkCreateWithNotificationBulkMutation 27043683338577412, _lib/group-invite-wire.js), accept-friend-requests (FriendingCometFriendRequestConfirmMutation 27351021931180810, _lib/friend-wire.js), add-friend (FriendingCometFriendRequestSendMutation), update-group-admins promote/demote/remove (GroupsCometMembersInvite/RemoveAdminMutation + GroupsCometRemoveMemberMutation 27148641238078140), approve-join-request (GroupsCometApprove/DeclinePendingMemberMutation 27132805893014911/27119718754378916), delete-group-post (useCometFeedStoryDeleteMutation 36213403264942057, input.story_id=base64 story_gid), set-account-language. Input SHAPE is captured off FB's OWN served JS (the commit-function variables:{input:{…}}); doc_id from _facebookRelayOperation or a browser-level CDP tap (autoAttach flatten → catches worker-target mutations the page misses). Capturing a lazy mutation module needs its UI state to exist first. Email-based FB jobs (invite-email-to-group, accept-group-invite-email, add-account-email) were DELETED.

Runner in-page-fetch capture — FIXED (adapters/_lib/gql-tap.js). The in-page page.evaluate fetch('/api/graphql') a replay fires does NOT surface on the CDP Network.* socket (a replay job used to show "0 graphql"), so the passive wires + schema miner + fb_graphql_call got nothing from the jobs richest in FB data. Now the runner mounts an in-page GraphQL tap (buildGqlTapSource → wraps fetch+XHR over the SAME bridge page.evaluate uses, clones each /api/graphql response before the app reads it, reports via the __bbGqlTap CDP binding + a window-array fallback) and foldGqlTap merges them into network.gqlCalls at stop() — identical shape to a natively-captured XHR. So every wire-replay job now feeds the passive wires: proven live — list-joined-groups went from 0 graphql → folded 13 · 20 req · 13 graphql → passive harvest 90 group · 90 membership. Gated BLUEBUT_INPAGE_GQL_CAPTURE (default ON). The source:'inpage_tap' tag marks folded calls.

Run an adapter

The bluebut-rest DB key is sourced from keyvault (bluebut/config/rest-service-key) by _lib/db.js — no env export needed (keyvault needs no creds: defaults to keyvault.hostbun.cc + bearer ddash). The runner is cloakbox-only — it resolves the account through the cloak-cdp HTTP API (POST /api/call, key ddash), no OPENCLI_CDP_ENDPOINT:

node bin/bluebut-adapter.mjs adapters/facebook/<cmd>.js --account <slug>
#   → cloak-client POST https://cloak-cdp.hostbun.cc/api/call {tool:cdp_load,args:{slug}}
#     (gates + egress-verifies + injects the session) → drive → {tool:cdp_save}.
#     Only accounts with a cloakbox device run (catalog verdict 'run'; the other
#     ~300 need a device minted — add-account skill).
#   Override the platform base/key with CLOAK_API_BASE / CLOAK_API_KEY (default ddash).

⛔ NEVER ssh-tunnel to pbox — the gateway is PUBLIC

cdp_load returns a public gateway origin (https://cloakbox.hostbun.cc?fingerprint=<seed>). Both drive paths reach it from any box with no tunnel: resolvePageWs → the public wss://cloakbox.hostbun.cc/fingerprint/<seed>/… (opencli page API), and cdp_drive → server-side over the public POST /api/call. Proven live from a laptop: node bin/bluebut-adapter.mjs adapters/facebook/whoami.js --account joel-skola → ok:true, no tunnel. Do NOT ssh -fNL 39555:127.0.0.1:39555 pbox and do NOT set CLOAK_ENDPOINT_BASE to a tunnel — that loopback path is retired. CLOAK_ENDPOINT_BASE survives only as a legacy origin-override (private/on-box gateway); unset (the default) uses the public origin. Collapsing to cdp_drive-only (kill the direct ws) is an OPTIONAL simplification, not a reachability need.

Sanity-check the platform + list runnable accounts without launching anything:

curl -s 'https://cloak-cdp.hostbun.cc/api/health?key=ddash'
curl -s 'https://cloak-cdp.hostbun.cc/api/launchable?key=ddash&service=facebook&runnable=1&summary=1'

• Streamed events → stderr (JSON lines); final result → one JSON object on stdout.

fbcli() {  # usage: fbcli <account> <cmd> [args…]  (cloakbox-only; over the public HTTP API)
  local acct="$1" cmd="$2"; shift 2
  node "$PWD/bin/bluebut-adapter.mjs" "$PWD/adapters/facebook/$cmd.js" --account "$acct" "$@"
}

From the dashboard

runCli/runCliStream POST to the bridge (VITE_BRIDGE_URL); it maps {site, cmd} → adapters/<site>/<cmd>.js, spawns the runner, streams stderr as SSE. Missing file → 404. Hosted is not view-only: prod bakes VITE_BRIDGE_URL → a token-gated bridge (bluebut-bridge.blpk.cc, Coolify, Dockerfile.bridge); BRIDGE_TOKEN gates it, build bakes VITE_BRIDGE_TOKEN so bridgeAuth() sends the bearer.

Source of truth + discovery

• adapters/ IS the source. Vendored originally from devdashco/toolbox, owned here now — toolbox is NOT in the runtime path. Edit the file; next run picks it up. Cherry-pick upstream fixes manually.
• Box: chromebox-fb at https://fb.chrome.blpk.cc (image devdashco/toolbox @ chromebox-fb). The old shared chrome.blpk.cc is NOT ours.
• GET <box>/chrome/profiles → accounts, cdp_url, spawn status.
• <box>/selkies/?token=<VNC_PASSWORD> → Selkies remote desktop (UI "VNC" button, vncUrl()). Token = SELKIES_MASTER_TOKEN = VNC_PASSWORD (ddash), proxied at /selkies/ by proxy.py. noVNC (/vnc/) is a fallback.

Adapter reference (facebook site)

• Session/identity: load-session (from keyvault via the account's proxy), login (re-auth stale creds), whoami. Page act-as = --as-page (see the pointer-model block); load-page-session is retired. Fresh onboarding = the add-account skill (cloakbox), not a box adapter.
• Messaging: via the Messenger box (site:'messenger') — sync-inbox (→ fb_thread/fb_message, all folders) + send-message ⭐ (BROWSER-FREE browser:false — SendMessageTask over the account's PERSISTENT LightSpeed socket via daemon /ls-send, type-15 → whatsmeow; no cdp_load, no DOM composer).
• Groups — discovery/membership: list-joined-groups ⭐ (doc_id 9974006939348139), get-user-groups ⭐ (groups + role + invites), get-group (detail+admins; write-back by default --persist → fb_group+fb_group_member+fb_account_group), get-group-join-config ⭐ (GroupsCometRequestToParticipateOnJoinDialogQuery doc_id 27156146040745454, _lib/join-config-wire.js → join questions/rules/flags), ingest-groups, create-group ⭐ (useGroupsCometCreateMutation), join-group, accept-admin-invite, approve-join-request ⭐ (GroupsCometApprove/DeclinePendingMemberMutation), invite-to-group ⭐ (_lib/group-invite-wire.js).
• Groups — editing (admin): update-group-admins ⭐ (--promote/--demote/--remove, self-verifying), update-group-location, update-group-description, update-group-cover.
• Groups — posting/scraping: create-group-post ⭐ (ComposerStoryCreateMutation text, own + act-as-Page --as-page → group_post+fb_post; DOM fallback for IMAGE only), delete-group-post ⭐ (useCometFeedStoryDeleteMutation doc_id 36213403264942057, targets base64 story_gid, ownership-gated, verifies gone), get-group-feed ⭐ (feed replay → fb_post+fb_person+fb-bot feed; --group/--groups/--all = every joined group, --max-groups N stalest-first), scrape-new-members ⭐ (_lib/member-request-wire.js), get-post-comments ⭐ (inlined permalink, _lib/comment-wire.js → fb_comment, no DOM click), get-group-insights ⭐ (GroupsCometForumInsightsGrowthRootQuery doc_id 26096051466719514, admin only).
• Social graph: add-friend ⭐, accept-friend-requests ⭐, list-friend-requests ⭐, list-friends ⭐, list-users.
• Pages: list-pages ⭐ (_lib/pages-wire.js → fb_page/fb_account_page), get-page-insights (DOM — BizKit DGW WS subscription, not a doc_id).

Bulletproofing: every mutating admin adapter follows never trust a click. failWith() attaches screenshot + context + strategies and reclassifies status:'blocked' on an FB block/checkpoint; okWith() reports the verified end-state. The UI chain (promoteAdminChain/addAccountAsAdmin) adds an independent get-group confirmation → verdict (verified | pending_unverified | blocked | failed). Drift canary: npm run canary:admin runs the full cycle, ships to HyperDX, exits non-zero on drift.

Semantic model

Layer 1 — Infrastructure: are our accounts working?

FB account record → keyvault (canonical). Client = adapters/_lib/keyvault.js (MCP keyvault.hostbun.cc/mcp, bearer ddash); sessions.js reads/writes it for site==='facebook'.

One namespace, owner-as-field: facebook/accounts/<slug|id> (ACCOUNT_PREFIX) holds ALL FB accounts. Full rows carry owner=bluebut (R/W); droidfleet farm blobs carry tag df-sync/no owner (droidfleet is their writer, bluebut reads them as a sync source). Tell ours apart by owner, NEVER by a key prefix.

keyvault is the SOLE account store — chromebox_sessions is retired. kv_list caps at ~100 — use kvListAll()/kvListAccountRows().

⛔ PAGES ARE POINTERS, NOT ACCOUNT ROWS — the strict pointer model

A Facebook Page has no login of its own — FB has no page credentials; you "act as" a Page by overlaying i_user=<page_fb_id> on its managing PROFILE's authed session. So the invariant:

• ONE keyvault account row per real login identity = the manager PROFILE (account_type='profile', its creds + storage_state + proxy + device). A keyvault row is NEVER account_type='page' — enforced at the write boundary (saveSession throws on account_type:'page'; test in sessions.test.mjs).
• Pages live only as POINTERS: fb_account_page (bluebut-db = source of truth) + the manager row's managed_pages[] (kv projection the loader reads). Each pointer = {page_key(=asset_id), page_fb_id, name, switch_method}, self-healed by the managed-page passive wire.
• Act as a page = --account <manager> --as-page <page_fb_id|name> (runner resolvePageActor reads the pointer off the manager's managed_pages; overlays i_user; VERIFIES FB flipped). No page account, no jar copy, no separate proxy — the page rides the manager's session/proxy/device.
• Retired: the standalone facebook/accounts/<page> rows + load-page-session/loadPageSession (a page row was a drifting copy of the manager's jar+i_user that duplicated identity/proxy/fingerprint and caused the philip→bofrid.se-page identity corruption). The 5 legacy page rows were purged 2026-07-07 (backup in the migration scratchpad); load-page-session now throws a deprecation → --as-page. The passive freshenOwnIdentity never infers account_type (ownIdentityPatch).
• UI: the Accounts grid nests Pages under their manager sourced from managed_pages (synthetic view-only rows, Accounts.tsx byManager/pageSessions); a Page is view-only with one action (Act as Page → --as-page), never an editable account row.

Bridge/UI: GET /accounts/registry (canonical list), POST /accounts/sync-keyvault, POST /keyvault/account (writeback).

The UI/registry sources the account LIST + proxy DISPLAY from keyvault (the sessions query → /accounts/registry); the box /accounts view only AUGMENTS live runtime state (spawn status/pid/idle) — never gate account data on box reachability (a truth-ladder violation: read the canonical store, not the presentation surface). All account R/W goes through keyvault.js; chromebox_sessions REST is dead. proxy is keyvault-canonical (only cdp_port is box-local).

~90+ accounts (named + ~80 df-* farm), all account_type='profile' (Pages are pointers). Named profiles: pojtie, joel-skola, mrkoll, william, philip, oskar-wik. Active: pojtie, joel-skola. philip manages 9 pages (incl. bofrid.se).

joel-skola is the TEST account. Use it for any manual/live end-to-end check (cloakbox cdp_load drives, wire probes, passive-wire smoke tests). It's the default cloakbox test account (migrated 2026-07-08, seed 13269) and manages the Uthyra.se page. Don't burn a real outreach account on a test.

Layer 2 — Entity graph: what do we know about the FB world?

• fb_group_member is FB's membership edge — the SINGLE source of admin-ness. One row per (fb_group_id, fb_user_id) with role (admin | moderator | member). No separate admin table, no is_admin/my_role on fb_account_group. "Our admins of group G" is derived: role='admin' ∩ our accounts' fb_ids (ourAdminsOfGroup in util.tsx). Roster roles written via upsertMembers in _lib/group-sync.js. fb_user_id is a bare numeric ACTOR id (NO FK): a group member/poster is a User (fb_person) OR a Page (fb_page — a page joined-as-page or posting-as-page; our own pages are members of 100+ group slots). A single-table FK would reject Page members.
• fb_person is the ONE User/lead/actor hub — canonical on the numeric fb_id (UNIQUE; the only stable FB identity — vanity/pfbid/profile_url are aliases; see [[reference_fb_identity_model]]). Holds Users AND company/posting Pages (an actor), distinguished by is_company/company_name. Fields: fb_id, profile_url (last-seen alias), email (admin_scrape/questionnaire — high value), intent (seeker|landlord|unknown, set by classify-posts), intent_confidence (explicit|inferred), outreach_status (new|contacted|replied|…, the DM-dedup surface), first_seen_channel, city. fb_user + fb_profile (redundant User tables) merged in + dropped 2026-07-08.
• fb_person_signal — immutable event log, one row per action (joined_group, posted, dm_reply). Append only.
• group_post — every group post Bluebut made: fb_group_id, group_url, chromebox_account, body, post_url, status (pending|posted|failed|skipped), skip_reason (cooldown|no_session|access_denied|blocked), posted_at.

Layer 3 — Activity log: what have we done?

fb_sent_messages (DMs) + fb_broadcast_posts (group posts) live on bofrid.dev — legacy fb-bot, read-only (queried for dedup + cooldown). Never write it.

Facebook anti-automation — the most important operational constraint

FB monitors posting behaviour across accounts/groups; it shapes every architectural decision. The accounts are the asset — temp-block = can't post/scrape/DM; perm-block = gone.

What FB detects: velocity (3+ groups/~1hr spikes risk; 2+ hrs rarely triggers), content fingerprinting (identical text = spam hash), timing regularity (use jitter), cross-account coordination (overlapping content/window), IP reputation.

Rules enforced in code:

1. Min 8 min between posts/account, randomised 8–15 min. Never fixed.
2. Max ~4 posts/account/hr. Exceed → route to another account or slow down.
3. Per-group cooldown ≥ 7 days. Check group_post (bluebut-db, posted) and fb_broadcast_posts (bofrid.dev, success) before including; show "last posted N days ago" for override.
4. Text variation. Never identical text to >3 groups/session — warn + prompt.
5. Stop on block. aborted_reason ~ "blocked"/"restricted" → stop the batch for that account, surface prominently.
6. Dedup before DM — "have we messaged this person? block". PERSON-level, keyed on the canonical numeric fb_id (messenger/lib/dm-dedup.js alreadyMessaged → checks fb_message is_self across the peer's threads + the fb_person hub messaged_at/outreach_status; stampMessaged on send). Wired into send-message before ALL paths (plain/E2EE/DOM) via --abort-on-prior (default on). The fb-bot legacy fb_sent_messages (bofrid.dev) is folded in as outreach_status='contacted' where resolved (the ~10k→fb_id import is a pending backfill).

Two acquisition channels (don't conflate)

• Channel A — Admin scraper (scrape-new-members, admin, WIRE): replays the admin_activities participation-change list + the per-activity "See details" dialog (_lib/member-request-wire.js) → the FULL member-request object: numeric fb_id, real profile_url, account_created_at, city (+ city Page id → geo), education, work, about_me, membership + rules-agreement enums, the structured questionnaire answers (where email + intent live), and the action enum → fb_person + fb_person_signal. Highest value — email reaches them via the Bofrid platform.
• Channel B — Feed scraper (get-group-feed, member, wire): replays the feed GraphQL for /groups/<id> → post content + poster + engagement/media → fb_post + lazy fb_person.

Categorization (in-repo, WIRE + LLM — the funnel §3, SHIPPED 2026-07-08): classify-posts (browserless job, Strategy.PUBLIC) sends each scraped fb_post to llm.hostbun.cc (claude-haiku-4-5, _lib/llm.js + _lib/judge.js) → ONE typed struct: post_type (rental-listing | listing-seeker | none | unknown) + is_company/company_name + confidence + structured housing fields. By type it writes post_extract_listings (offers: rent/rooms/sqm/area/company/contact…) or post_extract_seekers (demand: budget/desired_area/household/move_in…), stamps fb_post.classified_at, and refreshes the fb_person.intent cache. Replaces the old regex classifyPost + the external fb-bot classifier. NOT fb_judgment/housing_extract (an earlier draft — superseded by the two standard rental tables).

Signal → Person promotion: when get-group-feed/the passive post wire resolves a poster, promotePersonFromPost (post-sync.js) upserts fb_person on the canonical fb_id + links the post + appends fb_person_signal 'posted'.

Group post broadcast model

Different from fb-bot's listing broadcaster: content is a campaign message, groups picked manually by the present operator, output → group_post (bluebut-db), dedup (group_url, 7 days), no queue/poller/approval/manager — the operator IS the approval; direct runCli per group with live feedback.

Account routing (computed fresh): (1) fb_account_group is_member=true (admin via fb_group_member role=admin ∩ our fb_ids) → (2) filter to active session (last_status='logged_in') → (3) prefer admin → (4) prefer UI-selected → (5) none active → skip no_session.

⛔ Three things are called "post" — never conflate them

The Broadcast page (ui/src/pages/Broadcast.tsx) is the ONE "one content → many groups" surface (the old separate Listings page was consolidated INTO it 2026-07-09; /listings is now an alias route). Its listing table + the per-listing detail drawer (ui/src/pages/broadcast/ListingDetail.tsx) sit on top of three confusable objects:

The listing→our-posts link is group_post.listing_id — nothing else. Never a URL/text match, never fb_post. Because the listing object lives on a DIFFERENT database, listing_id is a bare text cross-DB pointer with no FK possible (same shape as the geo slug-pointer) — it can dangle; treat it as a soft reference. "Never broadcast" (zero group_post rows for a listing_id) is a first-class state, not an error.

Two rollup VIEWs already exist — use them, don't re-derive:

• group_post_stats — per-GROUP (posts_count, last_post_at, listings_count, last_listing_at). Powers the Groups index columns.
• listing_broadcast — per-LISTING (attempts/posted/failed/blocked/groups_live/verified_posts/batches). The authoritative "how did each listing's broadcast go" rollup — the same thing the detail drawer shows. The drawer reads a per-listing group_post?listing_id=eq.<id> query (unbounded); the Broadcast grid's rollup column re-derives it in JS off the page's global 500-row groupPosts cache (fine for recent listings; point at the view if a bulk/old-listing view needs it uncapped).

Where to build it — bluebut vs fb-bot vs platform

Default to bluebut when a human operator does something with FB (a human is present → no queue/poller/approval). Not bluebut for unattended automation (→ fb-bot/cron-fb-growth), listing/intake/geo (→ bofrid platform), or read-only history display (query bofrid.dev directly).

Recipe — "add X for bofrid": (1) FB work → adapter in adapters/<site>/; (2) state → idempotent SCHEMA.sql (site-agnostic → root); (3) UI → workspace tab (per-group) or batch page (cross-group) using Ui.tsx + runCli; (4) enforce anti-automation before any FB write; (5) the operator is the queue.

Traffic capture — sniffer + HAR

Entire subsystem is PLATFORM-OWNED under cloakbox: the platform's always-on wiretap captures every seed into a wiretap schema + MinIO + per-session HAR (wiretap_grep_traffic/_search_payloads/_export_har). The sniffer, netcapture.js, har*.js, gql-tap.js, traffic-store.js + the capture loop below all move to the DELETE list once migrated; bluebut keeps only its *-wire.js recognizers, run over the entities a cdp_drive gql returns or the warehouse. CAPTURE = platform, RECOGNIZE = bluebut.

chromebox-sniffer (bin/chromebox-sniffer.mjs) — always-on daemon, ships ALL box browser activity to HyperDX tagged by account (polls /chrome/profiles, browser-level CDP per profile, records request+nav). OTLP → service.name=chromebox-traffic. npm run sniffer; bin/Dockerfile.sniffer.

Every job is captured by the RUNNER, not the daemon — per call it drops a kind:'job' start/end pair + the full per-request trail (source=runner) carrying account/cmd/job_id. The daemon is a best-effort firehose for traffic the runner can't see (manual noVNC).

Debug from traffic (MCP hyperdx_sql, connectionId='6a0dd8f074371384ffe07f18'):

SELECT Timestamp, SeverityText, LogAttributes['kind'] AS kind, LogAttributes['status'] AS status, Body
FROM otel_logs
WHERE ServiceName='chromebox-traffic' AND LogAttributes['account']='<acct>' AND LogAttributes['job_id']='<id>'
ORDER BY Timestamp;

Rule of thumb: session/nav bug → kind='nav' (/login/?next= = cold/blocked, /checkpoint/); API/permission → SeverityText='error' + gql_name; "reaching FB?" → the job-start/job-end pair + ok/duration_ms.

HAR — full-fidelity archive (everything: headers, cookies incl. live c_user/xs UNREDACTED, postData, response bodies up to 16 MB lossless, WebSocket frames as _webSocketMessages — Messenger/MQTT publish+ack; HAR 1.2 → Chrome DevTools → Network).

• Two stores, by design: the gzipped HAR blobs live in the private har bucket (bluebut-minio MinIO/S3, public:false — account-takeover material; cut over from the hostbun Supabase bucket, har-store.js → S3_ENDPOINT); the tabular index (har_recording + traffic_entry, one row per request incl. WS sockets) lives on bofrid.dev, NOT hostbun (it's a ~277k-row/day firehose — kept off the shared operational DB). traffic-store.js creds() → BOFRID_SUPA_URL. The link is traffic_entry.recording_id → har_key → bucket. Read only via the token-gated bridge.
• WS capture gate WS_CAPTURE=1 (cheap, frames only) is independent of the heavy full-body HAR_CAPTURE; HAR_CAPTURE=1 implies it. E2EE: we capture the encrypted publish+ack (proof of send), never plaintext/read-receipts.
• ⚠️ ALWAYS capture WebSocket frames — the page CDP target alone NEVER sees them. FB's realtime sockets (lightspeed/realtime/streamcontroller/edge-chat/e2ee) each live on a separate CDP target; a page-only capture records ZERO frames while hundreds fly. Fix (both engines): a second, browser-level CDP connection (/json/version → webSocketDebuggerUrl) with Target.setAutoAttach({autoAttach,flatten}), re-armed on each attachedToTarget, routing Network.webSocketFrame* into the sockets map (lazy-materialize on first frame — long-lived MQTT never fires webSocketCreated). Runner: netcapture.js wsApply + the tap. Under cloakbox the platform wiretap owns this browser-level WS capture. If a HAR shows 0 WS frames, the browser-level tap is missing — that's the bug.
• Keys: per job → job/<job_id>.har.gz (linked on job.har_key); sniffer rolling → <account>/sniffer/<ISO-ts>.har.gz. Local copy next to the JSON artifact.
• Per job (guaranteed): runner finally → netcapture.stop() → buildHar → gzipHar → uploadHar('job/<id>.har.gz') → sets har_key. Best-effort. Pieces: adapters/_lib/har.js, har-store.js, netcapture.js. HAR blobs use the S3/MinIO creds (S3_*); the DB key comes from keyvault.
• Sniffer always-on (OFF by default): HAR_CAPTURE=1 on the sniffer's Coolify app; tuning HAR_ROLL_MS/HAR_ROLL_MAX/HAR_BODY_MAX/HAR_INFLIGHT/BLUEBUT_CAPTURE_BINARY. Captures live c_user/xs fleet-wide → deliberate outward decision.
• Retrieve: GET /har/blob?job=<id> (or ?key=<bucket-key>), GET /har/list?account=<acct> (or ?prefix=job). gunzip → drag into DevTools.
• Analyze offline (reads .gz directly): point DuckDB at the HAR gzips (wiretap_export_har pulls them from the platform) — the UI's DuckDB-WASM panel runs the same SQL. Do the FB-error scan keyed on the structural error CODE (368/1675004/1404xxx/1390xxx, never localized text) that catches rate-limit/abuse errors riding inside HTTP 200. For bulk sweeps: read_json('*.har.gz', maximum_object_size=2e8) + UNNEST(log.entries), filter response.status>=400 OR response.content.text LIKE '%"errors"%'.

Messenger box — read/send DMs through whatsmeow (the bluebut-e2ee daemon)

A self-contained subsystem at repo root messenger/ (NOT adapters/messenger/) that works FB Messenger off Facebook's own LightSpeed (LS) sync wire, not the rendered DOM — the truth ladder applied to Messenger. The legacy adapters/facebook/sync-messages.js scrapes localized aria-text (bottom rung: no hidden folders, no real ids, faked timestamps). FB web Messenger has no chat store in the DOM — it runs an in-browser LightSpeed DB the server drives with LS.sp(...) ops streamed in a /api/graphql/ response (lightspeed_web_request.payload). The box reads that same wire.

⭐ TARGET ARCHITECTURE (2026-07-09): whatsmeow is the ONE messaging path — LightSpeed is being DELETED

Messaging goes through whatsmeow ONLY (the bluebut-e2ee daemon = a registered encrypted-messaging device per account). The entire LightSpeed subsystem — the browser sync-inbox/sync-thread jobs, the persistent ls-session.go socket, lightspeed.go/ls-ingest.go, bin/ls-keeper.mjs, bin/poll-messenger-inbox.mjs, messenger/lib/decode.js/ls-procedures.js/passive-messages.js, the /ls-connect//ls-send//ls-ingest endpoints, the ls-keeper cron, MESSENGER_LS_PERSIST — is being removed. Say "encrypted messages", never "E2EE".

The model: whatsmeow holds a standing socket per account, decrypts EVERY inbound message (text, image, video, audio, file, sticker, location, contact, view-once — handler.go never drops a type) and POSTs it to the bridge. A decrypted message is self-contained (DecryptedMessage: thread_key + sender_id + timestamp_ms + message_id + message_type + text + attachments). The bridge materializes the inbox from that stream (handleE2eeIngest): UPSERT fb_message (+ fb_message_attachment), UPSERT fb_thread so the conversation appears, UPSERT fb_contact with the sender name resolved from the fb_person entity graph (whatsmeow only gives the numeric id). Send = send-message → the daemon's whatsmeow send.

The accepted losses (why this is a deliberate trade): no thread-list enumeration of idle conversations (a thread appears when it gets a message), no history (whatsmeow is realtime-only), no folders/unread, and no plain type-1 threads (older/business/page/group DMs that aren't encrypted are unreachable). Contact names come from fb_person, not a Messenger roster. Keep-alive = the reconnect-sweep (CAT minted via the cloakbox once/~24h; the one browser touch) + a register-once device — there is no ls-keeper anymore.

Status: cutover IN PROGRESS. Stage 1 DONE (handler.go captures all types; the bridge builds fb_thread/fb_contact from the stream). Stages remaining: send-message whatsmeow-only; delete the LightSpeed files/endpoints/jobs/cron/env; UI + doc rename. The prose below still describes the old LightSpeed subsystem — it is the migration backlog, not the target.

• How it runs: messenger/jobs/<cmd>.js declare cli({ site:'facebook' }) so the runner applies every protection (proxy/freeze gate, ensureFbSession, HAR, job ledger). Bridge routes site:'messenger' → messenger/jobs/<cmd>.js. UI = ui/src/pages/Messenger.tsx.
• No hardcoded doc_id — installLsTap (document-start) observes the page's own LS call, decode.js (JS port of mautrix-meta's LightSpeed step-VM) decodes via positional field maps (lib/ls-procedures.js), replayLs pages deeper. sync-inbox fails loud if it captures zero LS payloads.
• Jobs: sync-inbox (all folders incl. hidden Requests/Spam/Archived), sync-thread (one thread's full history), send-message ⭐ (auto-routed by thread type: PLAIN type-1 → SendMessageTask label 46 over LightSpeed via the daemon's messagix client; E2EE type-15 → the daemon's whatsmeow SendFBMessage(<peer>@msgr) — a plain LS task into a type-15 thread is accepted-then-DROPPED by FB, so E2EE MUST go through whatsmeow. send-message.js auto-detects type-15 via fb_thread; --transport=e2ee/dom force), manage-thread (mark-read verified; archive/delete/mute gated pending capture).
• E2EE runs on hostbun, self-heals tunnel-free. The bluebut-e2ee daemon is a Coolify app on hostbun (internal :8099, public fqdn https://bluebut-e2ee.blpk.cc; opens its own Noise socket to FB via the account proxy). Registers a per-account device (ICDC via a CAT), decrypts inbound type-15 → bridge /messenger/e2ee/ingest → fb_message (is_e2ee), and sends E2EE. CAT expires ~24h, only the live browser mints it. Durability = the reconnect-sweep: bin/e2ee-reconnect-sweep.mjs → cat-connect.js mintCatAndConnect mints via cloak-cdp cdp_drive + POSTs the daemon /connect with the stored wa_device_id (register-once). Two Coolify cron tasks: e2ee-reconnect-heal (*/15) + e2ee-cat-refresh (41 */6 --force). Register-once record = keyvault bluebut/e2ee-device/<slug>.
  • ⚠ The CAT mint MUST drive the PUBLIC cloakbox gateway (https://cloakbox.hostbun.cc), NOT a pbox loopback. cloak-client.js DEFAULT_DRIVE_BASE was http://127.0.0.1:39555 on a stale "cdp_drive runs on pbox" assumption — every mint got ECONNREFUSED 127.0.0.1:39555 and E2EE could not self-heal. Fixed to the public gateway (env CLOAK_DRIVE_BASE overrides only for a private/on-box gateway). Proven: reconnect-sweep mints + connects philip/pojtie; a full browser-free round-trip (philip→pojtie) lands is_self=true decrypted_by=self on the sender AND is_self=false decrypted_by=daemon on the recipient, same message_id.
• ⭐ WHAT MUST BE UP for realtime send+receive (per account) — and it RUNS IN PROD. Two daemon-held sockets per account, both on the prod bluebut-e2ee daemon: (1) the persistent LightSpeed socket — plain (type-1) receive+send, thread list, folders; auth = keyvault jar+proxy, browser-free, held up by bin/ls-keeper.mjs (*/5, pickAccounts runnable set). (2) the whatsmeow/E2EE socket — type-15 receive(decrypt)+send; auth = a CAT (the ONLY browser touch: minted once per <24h per account by driving the account's cloakbox seed), held up by the reconnect-sweep crons above. Both sockets live IN-MEMORY in the daemon, so every daemon restart (deploy) drops all of them → the keepers re-establish (LS fast+browser-free; E2EE via a CAT mint each). Keep daemon restarts rare. Local dev CANNOT hold these sockets — you consume the PROD daemon over its public URL (E2EE_DAEMON_URL=https://bluebut-e2ee.blpk.cc, token E2EE_DAEMON_TOKEN) and the public cloak gateway; send-message/sync-inbox run locally but the standing sockets + the keeper crons must run in prod (Coolify on hostbun) for anything to stay online.
• ⭐ Persistent LightSpeed sessions — REALTIME inbox, NO polling (daemon-held). messenger/e2ee/daemon/ls-session.go holds a long-lived messagix socket per account (a few MB, NOT a Chrome). This is the go-forward replacement for the browser sync-inbox poll (bin/poll-messenger-inbox.mjs, now DISABLED).
  • DOES IT NEED SYNC? NO. A standing socket receives every new message in realtime — FB pushes it down the open socket → decoded → bridge POST /messenger/ls-ingest → fb_thread/fb_message, the instant it arrives. There is exactly ONE sync per connection: the initial mailbox sync that fires once when a socket (re)connects, to catch up on anything that landed while it was disconnected. After that it is pure push — no poll, no sync-inbox job, no cron "refresh". If you're running a sync to see new messages, the socket isn't up; fix the socket, don't poll. (Carries metadata + previews + non-E2EE bodies; E2EE type-15 bodies still come only from the whatsmeow side.) Auth = the account's web jar (c_user/xs/datr) + its own proxy — no cloakbox device needed to READ.
  • The daemon is dumb; the keeper HOLDS the socket (it does NOT sync) (principle 12). bin/ls-keeper.mjs = the node keeper: enumerate the cloakbox-runnable accounts via the shared pickAccounts() (_lib/cloak-client.js → cdpCatalog, verdict run — NOT every logged-in jar; that pulled in dead/checkpointed g2g/df accounts we never use), load each jar+proxy from keyvault, POST /accounts/<slug>/ls-connect {fbid,proxy,cookies}. Its ONLY job is to keep the socket OPEN: each run it CHECKS ls_connected (the daemon /status reports it beside the E2EE connected — key on ls_connected ONLY, E2EE-up ≠ mailbox-up) and RECONNECTS only the DOWN ones — a healthy socket is left untouched. Any drop → a Telegram alert (via _lib/tg-notify.js) + non-zero exit. Daemon gate MESSENGER_LS_PERSIST (* = accept any slug the keeper pushes → the keeper is the sole gate); a real proxy is mandatory (a proxyless raw socket egresses the daemon IP → mass burn).
  • STATUS (2026-07-09): FIXED + working. The earlier "flap" was NOT the sockets — they hold fine (/accounts showed 5/6 connected:true); it was the keeper killing healthy sockets because the OLD /status reported the E2EE session (down post-restart) not the LS one → 404 → blind reconnect → start() stops-then-replaces the live socket. Fix (deployed): /status now reports ls_connected distinct from the E2EE connected, and the keeper keys on it → it leaves healthy sockets alone (proven: keeper run reports joel-skola/philip/pojtie ✓ up, 0 reconnects; philip + pojtie ingested ~30 realtime msgs each in a 30-min window). s7-amelia-bontin is flaky (LS HTTP 502 on connect, won't hold — account-specific, open). The ls-keeper Coolify cron is currently REMOVED (was churning under the old bug); re-add */5 now that it no longer churns.
• Schema (messenger/SCHEMA.sql): per-viewer-scoped — fb_thread/fb_message/fb_contact/fb_thread_participant/fb_message_reaction/fb_message_attachment. rpc/fb_schema_ingest self-applies new columns.
• WS link: encrypted MQTT publish+ack frames land in the per-job HAR as _webSocketMessages (WS_CAPTURE=1) — proof-of-send, never plaintext.

A messenger job's decoded wire + _webSocketMessages sit in its per-job HAR (GET /har/blob?job=<id> → gunzip → DevTools). 0 graphql in the step log is expected — LS rides one lightspeed_web_request payload, not named-query traffic.

UI pages

Four pages — ui/src/App.tsx. Nav: Groups → Groups; Automation → Jobs; Admin → Accounts, Tools.

A retired lens (Pipeline/Inbox/Outreach/Scraper) comes back as a workspace tab (per-group) or batch page (cross-group), never a top-level one-off.

Geo association for FB groups (planned)

Each FB group covers a geography. Polygons live in the geo project (geo_regions/municipalities/geo_areas, served by geo-bofrid geo.bofrid.eu/api/geo); fb_group is in bluebut-db — cross-DB FKs impossible. Plan: slug-only — add geo_slug to fb_group; (geo_level, geo_slug) is the canonical pointer, resolved on demand via geo-bofrid. Out of scope: storing geom, replicating geo tables, moving fb_group into geo.