Cloudflare-native local development (current state)

Supersedes the GCP-emulator sections of 6. Local development. The platform retargeted from GCP to Cloudflare Workers (see docs/architecture.md); Postgres, Pub/Sub, and Firebase emulators no longer participate in the local dev loop. Local state lives in D1 (SQLite) via wrangler, and the gateway runs under wrangler dev / workerd, not Node.

TL;DR — standing up the stack

cp .env.example .env       # then rebrand values (see below)
pnpm install --frozen-lockfile
pnpm dev:bootstrap         # D1 migrations + dev tenant seed (local wrangler state)
pnpm dev                   # package watchers + gateway (wrangler dev) + agent (tsx watch)

Readiness banner: [mnemose-dev] Core runtime ready. Health check: curl localhost:4000/health → {"status":"ok","service":"mnemose-gateway","runtime":"cloudflare-workers",...}

GraphQL at http://localhost:4000/graphql enforces auth: {"errors":[{"message":"Missing Authorization header","extensions":{"code":"UNAUTHENTICATED"}}]} is the expected unauthenticated response.

`.env` (required by `tsx --env-file`)

services/*/package.json dev scripts load --env-file=../../.env. Without that file tsx exits 9 (node: ../../.env: not found). Copy the example and rebrand:

blackice → mnemose, BLACKICE → MNEMOSE (URLs, project IDs, emails)
Ensure DEV_AUTH_BYPASS=true and DEV_AUTH_TENANT_ID=11111111-1111-4111-8111-111111111111 are present (the bootstrap seed relies on them)

What `pnpm dev` actually runs

scripts/dev-runtime.mjs:

dev:prepare — gen:app-catalog + build of all @mnemose/* packages
5 package watchers (logger, kernel-protocol, bootstrap, db, domain) in tsc --watch
Gateway via wrangler dev --local --port 4000 (workerd — the D1/R2/KV/ Queues/DO bindings from the root wrangler.toml are available locally)
Agent via tsx watch from services/agent — an exports-only module (command processor), no HTTP listener

pnpm dev:bootstrap applies D1 migrations and seeds the dev tenant via wrangler d1 against local state.

GCP-legacy migration (complete)

All packages that previously imported createGcpPlatform have been migrated to the CF Worker/DO/Queue architecture:

Package	Migration
`@mnemose/mcp-mnemose-kernels`	`HttpEventBus` (POSTs to gateway queue endpoint)
`@mnemose/mcp-mnemose-services`	`createCloudflarePlatform` with sandbox-injected bindings
`@mnemose/cli`	GCP-free (no `createGcpPlatform` imports)
`services/kernel-broker/src/server.ts`	`HttpEventBus` + `better-sqlite3` for Node runtime
`services/loop-host/src/index.ts`	`CfSecrets` / `CfCloudCredentials` with injected bindings
`services/agent/src/command-subscriber.ts`	`createCloudflarePlatform` from Worker env bindings

services/commands/bootstrap-cloud-project and services/commands/bootstrap-organization were rewritten CF-native (no GCP IAM minting; workload-identity event fields are undefined).

The agent package (services/agent) still has 12 pre-existing command-subscriber.ts type errors (CI runs continue-on-error); they do not block tsx execution or the dev runtime.

Common failure modes (this container)

Symptom	Cause	Fix
`Cannot find module .../node_modules/typescript/bin/tsc` during build	`node_modules` was installed on Windows (WSL `/mnt/d/...` absolute symlinks), mounted into the container	`rm -rf node_modules && pnpm install --frozen-lockfile`
`.npmrc` `WARN Failed to replace env in config: ${NPM_TOKEN}`	Harmless — token interpolation warning when `NPM_TOKEN` unset; `@freeside-collective/*` is public now	Ignore
`Address already in use 127.0.0.1:4000`	Orphaned `workerd`/`wrangler` from a previous run (kill parent `wrangler` process, not only `workerd`; it respawns)	`pkill -9 -f "wrangler dev"; pkill -9 -f workerd`
Agent exits instantly, `No projects matched the filters`	Concurrent `pnpm --filter` workspace-resolution race (7 pnpm processes starting at once)	Fixed in `scripts/dev-runtime.mjs`: processes spawn with per-package `cwd` instead of `--filter`
Runtime never reaches `Core runtime ready` with services healthy	Readiness regex didn’t match actual banner (`Ready on http://localhost:4000`, agent’s silent `tsx watch`)	Fixed in `scripts/dev-runtime.mjs` (match `ready on`, `tsx watch`; test raw chunk + trailing line — chunks can split patterns)
Gateway `dev` script fails on missing `src/server.ts`	`server.ts` deleted in the Cloudflare retarget; `worker.ts` is the entry	Fixed: gateway `dev` now `wrangler dev --local --port 4000`
`node: ../../.env: not found`, exit 9	Root `.env` missing	See `.env` section above
`services/agent` build fails citing `tenantId`	Pre-existing branch type errors	Out of scope; tracked by CI `continue-on-error`

D1 local data

Wrangler local D1 state lives under .wrangler/state/. Reset with:

rm -rf .wrangler/state
pnpm dev:bootstrap

Environment parity

The devcontainer remoteEnv still contains GCP-era vars (GCP_PROJECT_ID, DATABASE_URL pointing at Postgres, Pub/Sub and Firebase emulator hosts). They are inert for the CF-native runtime but kept for console/Vite compatibility. The authoritative runtime config is the root wrangler.toml ([vars], D1/R2/KV/Queues/DO bindings).