Summary

End-to-end smoke testing the brain ingest path against the real Unison API (the part CI never exercises — live tests are gated behind UNISON_TOKEN) surfaced two real failures plus two doc bugs. This PR fixes all of them.

• 429 rate limiting killed multi-file ingest. The brain rate-limits per API key with a slow-refill quota (measured: ~40 cold capacity, refill ~40/min, ~0.67 writes/s). BrainClient had no retry, so any non-trivial ingestBatch died with 429 rate_limited. Added automatic retry on 429/transient 5xx with exponential backoff + equal jitter (maxRetries default 8, honours Retry-After). Equal jitter (a growing floor) is deliberate — full jitter retries near-instantly back into the same quota wall.
• Mid-file failures left orphaned chunk docs. When a chunk write failed partway through a file, earlier chunks were already in the brain but the file reported as fully failed (paths: null), so the caller couldn't clean up the leak. pushChunks is now atomic per file: on failure it rolls back the chunks already written and reports them via IngestFileError.rolledBack.
• .env.example pointed at the wrong host (api.unisonlabs.ai → brain.unisonlabs.ai).
• AGENTS.md test count corrected (313 → 329) and README + AGENTS now document the per-key rate limit and the "keep concurrency low / split across keys" guidance for large repos.
• Gitignored .serena/ (machine-local).

New client-retry.test.ts adds fake-fetch contract tests (retry, backoff, Retry-After, no-retry-on-4xx, wire shape, rollback) — fully offline, no token needed, also closing the gap that the client had zero unit coverage before.

Test plan

• bun run build — passes
• bun lint — clean (only 4 pre-existing useLiteralKeys infos on untouched lines)
• bun test — 336 pass (329 prior + 7 new), 0 fail
• Live: UNISON_TOKEN=… bun test test/ingest.test.ts — 25 pass incl. real brain round-trip (whoami + ingest + delete)
• Live validation: 5-file / 24-chunk ingestBatch at concurrency 2, no manual pacing — library retry carried it end-to-end in 5.4s, zero orphans, read-back confirmed
• (Follow-up, not in this PR) wire a gated CI smoke job using a repo secret so the live ingest path is exercised on main

Known limitation (documented, not a code bug)

Whole-repo single-key ingest remains quota-bound by design — the server's own 429 message says "split work across keys". Retry handles spikes and small/medium jobs; large codebases should lower concurrency and/or split the file list across multiple keys.

Summary by cubic

Adds automatic retries for 429/5xx in BrainClient and makes per-file ingest atomic with rollback. Fixes multi-file ingest under rate limits and prevents orphaned chunks; updates docs and defaults.

• Bug Fixes

  • BrainClient now retries 429 and 502/503/504 with exponential backoff + equal jitter; honors Retry-After; maxRetries default 8.
  • pushChunks is atomic per file; on failure, previously written chunks are deleted and returned via IngestFileError.rolledBack.
  • Corrected default API host in .env.example; added offline tests for retry/backoff and rollback.

• Migration

  • Visibility: replace 'tenant' with 'workspace' throughout (ingest options, docs).
  • Paths: writable roots now include /workspace/ instead of /tenant/.
  • WhoAmIResponse.tenant renamed to workspace.

^{Written for commit 038eaf3. Summary will update on new commits.}