Single-workspace mode: DEFAULT_REPLICA_ID fallback for KV-miss rooms

[replicas-connector]

What

Adds an optional DEFAULT_REPLICA_ID env var. When set, dispatch.ts forwards messages from rooms with no KV mapping to that replica instead of calling POST /v1/replica, and pins the mapping on first successful send so subsequent messages route via the normal existing path.

When unset (default), behavior is unchanged — per-room auto-spawn continues.

Why

The current behavior spawns one workspace per Matrix room. For operators running a single long-lived workspace, this multiplies cost and fragments context. This change lets us point every new room at the same replica in one place.

How to enable

wrangler secret put DEFAULT_REPLICA_ID    # or set under [vars] in wrangler.toml

Set it to the UUID of the workspace you want all KV-miss rooms to use.

Safety

• Unset = legacy behavior (verified: else if (env.DEFAULT_REPLICA_ID) only fires when the var is truthy).
• Send failure to the default replica falls through to the existing fresh-spawn path — bot never goes silent.
• KV mapping is pinned only on success, honoring REPLICA_TTL_SECONDS the same way the fresh-spawn path does.
• No changes to the existing-replica branch, the poller respawn paths, the listener, or any encryption surface.

Files

• src/index.ts — declare DEFAULT_REPLICA_ID?: string on Env
• src/dispatch.ts — new else if (env.DEFAULT_REPLICA_ID) branch with KV pin
• wrangler.toml — documentation comment + commented placeholder under [vars]

Not merged — please review

Merging triggers the CI auto-deploy. Recommend: review diff → merge → set DEFAULT_REPLICA_ID via wrangler secret put → manually GET /admin/sync/start to kick the listener. Leave unset on first deploy to verify nothing regressed; flip the var on once green.

[capy-ai]

Capy auto-review is paused for this organization because the monthly auto-review limit has been reached. Increase the limit or turn it off in billing settings to resume automatic reviews.