SPEC — Cloud Brain engine work (for the 🧠 Brain / #042 session)

Owner lane: command-inbox/start-here.gs + ops-api/src/index.ts (the brain/inbox code). Worker 🐝 wrote this spec; the Brain/#042 session implements it so the shared-brain writes stay consistent (no duplicate facts) and parallel sessions don't clobber. Plan: .claude/plans/logical-coalescing-lovelace.md.
Created: 2026-06-12 by Worker 🐝. Tracker: outputs/cloud-brain-build.html.

Context the Bee already established

• ops-api base = https://ops-api.sam-0f0.workers.dev. Ingest contract (verified in ops-api/src/index.ts ~L1954–2035): POST /memory/ingest {token, reconcile, facts:[{category,fact,savedAt,source}]}; id = mem-<md5(source|fact)[:16]> (idempotent). Proven caller = migrateProfileToD1_(reconcile) in start-here.gs (~L3193) using sources profile-tab / context-tab.
• Auth = INBOX_SECRET (same value scripts use as inboxSecret).

PHASE 1

1. Auto-sync Claude Code memory → D1. New local memories (e.g. today's project_brain_inbox, project_mis_operator, project_worker_b_gabbai) aren't in D1 yet. Build a pusher that sends the MEMORY.md index lines (one fact each) to /memory/ingest. CRITICAL: use the SAME source string #042 used for the original 167-entry push (check the #042 ingest call) so re-pushing updates in place and does NOT create duplicate facts. Trigger options: a Claude Code SessionEnd hook in .claude/settings.json calling a scripts/memory-sync.ps1 (Bee can write the script once you confirm the source string + whether to send index-lines vs file-bodies), and/or a daily cron backstop. Recommend reconcile:false for this source initially (additive, safe) — per-source reconcile later.
2. Correction write-back (issue #17). In telegramBrainReply_, detect corrections ("no, it's X" / "actually Y" / "that's wrong, it's Z") → call existing rememberFact_ (new truth) + forgetFact_ (old) so D1 updates and retrieval stops returning the wrong fact. Log to event_log.
3. Nightly distill. Extend the existing DREAM cron (runNightlyDreaming / consolidateProfile_) to also fold the day's captures + corrections into clean Profile facts.

PHASE 2

4. Async dispatch lane. New command CODE <task> (alias FORBEE <task>) → write to a Dispatch store (new D1 table dispatch{id,task,source,status,created,result} OR a Dispatch sheet tab). Any Claude Code session drains status=open rows on open (extend the Brain_Feed read), runs them, writes result + status=done, and the bot relays the result to Telegram. This is what lets Sam command work with no live PC.
5. Scoped portal write endpoint (unblocks the cheat-sheet BUTTONS, #078). A narrow POST /cmd on ops-api that accepts ONLY an allowlisted set of safe commands from the CF-Access-gated portal (no INBOX_SECRET in the page) → forwards to the command inbox. Then outputs/bot-commands.html buttons can actually fire (until then they tap-to-copy).
6. NEWSESSION <bee|brain|mis> — Phase 3 dependent; routes to the bridge (below).

PHASE 3 — the Telegram → cloud Claude Code bridge

On the VPS: a small authenticated service receives {token, session, message} from the bot, runs Claude Code headless (claude -p / Agent SDK) in the named tmux session (each operator = its own session, re-becoming itself from its beacon), streams stdout back to the bot via Telegram. Bridge endpoint contract to agree with the Bee so scripts/ + the bot lane match. Security: chat-id allowlist, scoped token, confirmation-gate money/destructive/external actions, SSH-keys-only box. Detail: docs/CLOUD_BRAIN_PLAN.md Half B.

Bee is handling (don't double-build)

The operator beacons + recovery (done), docs/BOT_COMMANDS.md + outputs/bot-commands.html (cheat-sheet/buttons UI), the live tracker, the VPS stand-up checklist + the bridge client contract, scripts/memory-sync.ps1 (once you confirm the source string).