brane 0.1.1 → 0.3.1

package/docs/request-layer.md

@@ -0,0 +1,72 @@
+# The Request Layer
+
+Every call from the app to a daemon is **cross-origin** — the bundle is served
+from `brane.organelle.dev` (or another daemon's copy of it) while the daemon
+answers on its own Tailscale host. That fact is free on a LAN and decisive on
+a bad link, because CORS makes the browser *ask permission before asking the
+question*: a request that is not "simple" gets a preflight `OPTIONS` and may
+not be sent until the answer comes back.
+
+The cost was measured rather than assumed. On in-flight satellite wifi at
+**741 ms RTT** (`tailscale ping`, direct path — not a DERP relay and not the
+travel router), the app's four opening requests — narratives, folds, branes,
+protocols — were each aborted at exactly **10.00 s having transferred zero
+bytes**, every one still waiting on a preflight that had never returned.
+Nothing was slow. Nothing had started.
+
+Three things were wrong, and only the third is the one you would guess:
+
+| | Was | Is |
+|---|---|---|
+| Bodiless requests | `Authorization` + `Content-Type: application/json` → preflight | no headers at all, token in `?token=` → **no preflight** |
+| Preflight caching | no `Access-Control-Max-Age`; Chrome's default is **5 s** | `86400`, so a bodied request's preflight is a daily cost |
+| Timeout | 10 s, no retry | 60 s, with backoff on transport failures |
+
+`src/shared/api-request.ts` holds the rules, window-free so they can be tested
+without a browser — the same arrangement as `view-url.ts`, and for a sharper
+reason. **Breaking these rules is invisible on a fast network.** Put an
+`Authorization` header back on a GET and every local test still passes while
+the app becomes unusable at altitude, so the invariant is pinned by
+`src/test/api-request.test.ts`, which reads `expo/lib/api.ts` and asserts that
+no request sets that header and that `JSON_HEADERS` appears only where a
+`body:` does.
+
+| Piece | Does |
+|---|---|
+| `requiresPreflight()` | The CORS cost model itself — safelisted methods, headers, and content types |
+| `withToken()` | Token into the query string, joining an existing one with `&` and staying in front of a `#` |
+| `isRetryableMethod()`, `isRetryableError()` | What may be replayed |
+| `DEFAULT_TIMEOUT_MS` | 60 s |
+| `setCorsHeaders()` | `src/daemon/server.ts`; exported for `src/test/cors-preflight.test.ts` |
+
+Three decisions are less obvious than they look:
+
+**The token moves to the URL, and that is not a downgrade.** It arrived in a
+URL — the meld link that opens the app carries it (in the fragment, since the
+[View URLs](view-urls.md) change; before that, as `?token=`). These requests
+address the operator's own daemon, so no third party sees a `Referer` for
+them, and the query string here goes to the daemon and nowhere else. The daemon
+has always accepted the parameter, checked immediately after the `Bearer`
+header; nothing on the server needed to change to allow it.
+
+**Bodied requests still preflight, deliberately.** `application/json` is not a
+CORS-safelisted content type, and the way to dodge that is to label JSON as
+`text/plain` — a Content-Type that lies, and a trap for whoever reads the code
+next. The app reads far more than it writes, so the honest header is cheap;
+`Access-Control-Max-Age` is what makes it rare.
+
+**Only idempotent requests retry.** A timed-out `POST /api/spawn` is genuinely
+ambiguous — the daemon may have spawned the agent and merely been too slow to
+say so. Replaying that spawns a second one. An HTTP error is likewise an
+*answer* and never retried: a 404 will not change on a second ask, and a 500
+may have had effects. Only a request that provably never landed is safe to
+send again.
+
+**HTTP/2 would help and is not available.** One connection instead of Chrome's
+six means one TLS handshake instead of six, which is worth real time at this
+RTT. But all three WebSocket endpoints ride the HTTP/1.1 `Upgrade` mechanism,
+which HTTP/2 replaces with extended CONNECT (RFC 8441) — and `ws` does not
+implement the server side. ALPN is negotiated per origin, not per request, so
+advertising h2 would take the control channel, the MCP bridge and terminal
+mirroring down with it. It stays on the table as its own change, gated on a
+WebSocket transport that survives it.

package/docs/selection-store.md

@@ -0,0 +1,50 @@
+# The Selection Store
+
+The chat's message selection is a store outside React state
+(`MessageSelection`, `src/shared/message-selection.ts`), and the two hooks
+that bind it (`expo/lib/selection.ts`) are the only React in it. The screen
+holds no selection state at all.
+
+It was `useState<Set<number>>`, and that shape had both a cost and a bug.
+
+**The cost is a cascade, not a copy.** A tap replaced the `Set`, which
+re-rendered the `[nid]` screen, which rebuilt `handleTimestampPress`
+(dependency: `selectedSeqs`), which rebuilt `renderItem`, which handed every
+mounted `MessageBubble` a new callback prop — so `memo` missed on all of
+them. Two bubbles changed color; two hundred rows and the screen above them
+re-rendered.
+
+**The bug is a stale closure, and it drops taps.** Two taps in the same
+React batch — a fast double-tap, a trackpad — and the second computed from
+the set the first had already replaced, silently undoing it. Measured in a
+headless browser against a real daemon: on `origin/main` two rapid taps left
+**one** message selected, on the store both. A store is single-writer and
+authoritative; a closure over a snapshot is neither.
+
+| Subscription | Who | Wakes when |
+|---|---|---|
+| `subscribeSeq(seq)` | each `MessageBubble`, via `useIsSelected` | *its* seq is selected or deselected |
+| `subscribe()` | the header (Export's count), the composer (`re`) | any change — one component each, which is the point |
+| none | the screen, `renderItem`, Export's press handler (`getSelected()` at press time) | never |
+
+Three details are load-bearing:
+
+**A clear notifies what was cleared, not everyone.** `clear()` wakes exactly
+the rows that were selected and returns them; an empty clear is not a change
+and wakes nobody. `replace()` wakes the symmetric difference. A broadcast
+would put the whole list back on the path this exists to keep it off.
+
+**The snapshot's identity is stable.** `useSyncExternalStore` compares
+snapshots by identity, so a getter that allocates re-renders forever. The
+ascending array is rebuilt on change and only on change, and an empty
+selection is one frozen shared array.
+
+**Buckets are dropped when their last listener unsubscribes.** Rows unmount
+as the list scrolls; without that, the per-seq map would grow by every
+message ever scrolled past.
+
+Pure and in `shared/` for the usual reason: `src/test/message-selection.test.ts`
+checks the notification rules without a browser, and
+`src/test/selection-wiring.test.ts` reads `expo/app/[nid].tsx` to hold the
+screen to the wiring — both spellings select messages, so only a source lint
+can keep the old one from coming back.

package/docs/session-affinity.md

@@ -0,0 +1,61 @@
+# Session Affinity
+
+A `claude` narrative whose Claude Code talks to Fireworks (an
+`ANTHROPIC_BASE_URL` on a `fireworks.ai` host) sends `X-Session-Affinity:
+<nid>` with its LLM requests. `ensureSessionAffinityConfig`
+(`src/session-affinity.ts`) runs on every spawn and revive, from `doSpawn`,
+`prepareAgentLaunch`, and the same-agent revive path in `src/daemon/server.ts`,
+and returns `{ args, env }`: CLI args for the agent and an env prefix for the
+tmux command. Fireworks uses the header to keep a session on one replica, and
+its per-replica KV prefix cache only stays warm that way. The nid survives
+revives, so the affinity does too. Every other claude spawn launches exactly as
+before. Opt out with `brane config session-affinity.enabled false`.
+
+The header name and its alternatives come from Fireworks' prompt-caching guide:
+`x-session-affinity` (header), `prompt_cache_key` (request body, the
+preferred field), `user` (body, fallback), and `x-multi-turn-session-id`
+(agent traffic). Claude Code can't set a body field (it has no config surface
+for one), so the header is what it gets. Cache hits show up as
+`usage.cache_read_input_tokens` on the Anthropic-compatible `/v1/messages`
+path, which the cost ledger already records, and in the
+`fireworks-cached-prompt-tokens` response header.
+
+Claude Code reads `ANTHROPIC_CUSTOM_HEADERS` (newline-separated
+`Name: Value`) from its environment. Where that value comes from decides how
+brane adds to it:
+
+**A settings file defines it.** A settings file's `env` block is written
+*over* the inherited shell value, and settings `env` values are not
+`${VAR}`-expanded (verified against claude 2.1.278). So nothing in the shell
+can add to it, and a shared fold file could only hold one literal nid. The
+workaround is `claude --settings <path>`, which outranks every settings file.
+brane writes one file per narrative at `~/.brane/session-affinity/<nid>.json`
+containing one key: the value from the highest-precedence file (local >
+project > user), with any stale affinity line stripped (case-insensitive
+name match, the same parse Claude Code performs) and the affinity line
+appended. That value includes whatever credentials the operator's headers
+carry, so the file is `0600` in a `0700` directory, re-tightened on every
+write. The operator's own settings files are never written. This was verified
+end to end against a header-logging listener: the nid arrives, the fold's other
+lines come through, and a hand-added stale affinity line is replaced.
+
+**Nothing defines it.** Then Claude Code uses whatever the *session's* shell
+inherits, which comes from the tmux server, and the tmux server need not share
+the daemon's environment. Reading the daemon's `process.env` into a
+`--settings` file would *replace* headers the session had and the daemon
+didn't. The first draft did exactly that, and an `X-Shell` header exported
+where tmux started disappeared from the wire. So the header goes in the tmux
+command's env prefix instead (`shellAffinityEnv`), and the session's own shell
+appends it to whatever it inherited. The Fireworks check does read the
+daemon's env as a last resort for `ANTHROPIC_BASE_URL`. If that misses a URL
+only the session has, the cost is affinity and nothing more.
+
+Managed settings still outrank `--settings`; delivering through them is out of
+scope.
+
+**Crush is deliberately left out.** It already sends `x-session-affinity` and
+`x-session-id` (a hash of its own session id), and that value wins over any
+configured `extra_headers`. A static `$BRANE_NARRATIVE_ID` entry was tried and
+never reached the wire. Crush's key changes when a narrative is revived,
+because crush starts a new session. Other harnesses have no observed Fireworks
+traffic.

package/docs/terminal-mirroring.md

@@ -0,0 +1,243 @@
+# Terminal Mirroring
+
+The terminal tab is a **mirror, not an attach**, and that is a design position
+rather than an unfinished one. `capture-pane` is a *read* of shared state, so
+any number of viewers watch one 100 ms capture loop with no tmux client
+attaching, no attach/detach churn, and sizing that is brane's policy
+(`fitWindowToViewers` — smallest active viewer wins, so a phone joining can
+never clip a TUI's bottom rows). Idle costs almost nothing: `content ===
+cap.lastContent` returns before a *diff* is sent, so a session waiting on
+`listen` produces no repaints and no client rAF work — only the resync
+heartbeat below. And because the frame is text rendered into DOM lines,
+selection, ⌘F and copy are the platform's rather than ours — an emulator would
+have us re-implement them.
+
+The mirror's own consequence is that **anything not in the pane's text has to
+be sent explicitly**. There is exactly one such thing, and it is the cursor.
+
+## The resync heartbeat
+
+Sending a diff only when the content changes is right, but it rests on an
+assumption the protocol never checks: that a frame the daemon *sent* is a frame
+the browser *rendered*. `c.lastContent` records the former and is read as
+though it meant the latter. Every way a browser can drop a frame — a
+backgrounded tab whose `requestAnimationFrame` never ran, a socket that
+reconnected into a wiped `<pre>`, an early return in `applyFrame` — therefore
+strands that viewer, and because the pane then goes quiet, *nothing ever
+corrects it*. The only repair is a page reload, which is not a repair the
+operator should have to know about. Observed in the wild as a phone showing an
+entirely black terminal while the daemon's socket was demonstrably serving
+frames the whole time.
+
+`TERMINAL_RESYNC_MS` (2 s) closes the class without an ack protocol: a viewer
+that hasn't been sent *content* in that long is re-sent the current frame,
+whatever the reason it fell behind. Any dropped frame self-heals within one
+interval.
+
+| Piece | Where | Does |
+|---|---|---|
+| `lastSentAt` | `TerminalClient` | When this viewer was last sent content. Cursor-only messages don't touch it — they carry none |
+| `isResyncDue()` | `src/daemon/server.ts` | The boundary, pure, so `src/test/terminal-resync.test.ts` can pin it |
+| `resyncStaleViewers()` | the capture loop | Runs on **both** paths — see below |
+
+Three details are load-bearing:
+
+**Both paths, not just the idle one.** The obvious place is the `content ===
+cap.lastContent` early return. The other is after the per-client fan-out, where
+a viewer skipped by `content === c.lastContent` is *exactly* the stranded case
+— its `lastContent` says it has this screen and its DOM says otherwise.
+
+**`lastSentAt: 0` is the "due now" sentinel.** A fresh socket and a `refresh`
+that just wiped the client's `<pre>` both set it, and against an epoch clock
+`now - 0` clears any threshold — so those viewers get content on the very next
+tick rather than waiting out an interval.
+
+**Idle stays cheap.** One ~1.6 KB message per viewer every 2 s, serialized once
+per tick and shared across viewers. On the client it is a full frame whose
+per-line diff finds nothing changed, so it writes no DOM. A busy pane already
+sends more often than this and is unaffected.
+
+## The stranded rAF
+
+The heartbeat guarantees the daemon keeps *offering* content. It does not
+guarantee the client can *accept* it, and there was one way it could not.
+
+Frames are coalesced through a single `requestAnimationFrame`, with
+`rafIdRef !== null` standing for "a drain is already coming". That reading
+holds only while the browser still intends to run the callback. **iOS Safari
+freezes a backgrounded tab and can drop the scheduled callback outright** — an
+app switch, a screen lock, an incoming call. The page resumes holding a
+non-null id for a drain that will never fire, and from that moment the guard is
+permanently closed: every later frame is stored in `pendingRafFrameRef` and
+none is applied. Unmounting is the only thing that clears it, which is to say a
+page reload. A pane that never got its first frame this way is not stale but
+*blank*.
+
+Note the interaction: **a stranded rAF swallows the heartbeat too**, delivering
+fresh frames every 2 s into a queue nothing drains. The two fixes are not
+alternatives; neither is sufficient alone.
+
+| Piece | Does |
+|---|---|
+| `RAF_DRAIN_DEADLINE_MS` (400 ms) | An arriving frame that finds one already waiting this long stops trusting the schedule: cancel the token and drain inline. Generous beside a 16 ms paint on purpose — a liveness backstop, not a latency budget |
+| `visibilitychange` → visible | Clear the stale token, drain anything pending, and `refresh()` the channel |
+
+The `visibilitychange` half earns its place because foregrounding is both the
+moment a callback was most likely dropped and the only moment repair is
+possible without waiting: an idle pane's next frame is two seconds out, and the
+`refresh()` is what restates a DOM that went stale for a reason the client
+never observed. It is gated on the pane being active: an inactive one
+has its DOM wiped and refreshed by `cleanRefresh` on activation anyway.
+
+**A frame arriving no longer means the pane changed.** That equivalence was
+free before the heartbeat and is what `applyFrame`'s auto-scroll was built on.
+"At bottom" is a 40 px band, so an identical frame every 2 s would yank a
+just-started finger-scroll back down for as long as the reader stayed inside
+that band — a window that recurs forever rather than a one-off, on every
+scrollback pane (alternate-screen panes are `overflow: hidden` and unaffected).
+`applyFrameLines` and `applyAppendLines` therefore **return whether they wrote
+any line node**, and the scroll follows that rather than the frame's arrival. A
+frame that changed nothing has nothing to follow.
+
+## The cursor
+
+One tmux invocation per tick carries both halves of a frame:
+
+```
+display-message -p -F "#{cursor_x} #{cursor_y} #{cursor_flag} #{alternate_on} #{pane_height}" \; capture-pane -e -p -S - -E - -t <nid>
+```
+
+Deliberately **one** call. A keystroke landing between a separate cursor query
+and its capture would paint the block a cell away from the character it belongs
+on — the one artifact a cursor cannot have. It also replaced the periodic
+`alternate_on` probe, so the per-session exec count went down.
+
+| Piece | Where | Does |
+|---|---|---|
+| `TERMINAL_STATUS_FORMAT` | `src/daemon/server.ts` | The five fields, all numeric, so the parse cannot be ambiguous |
+| `parseTerminalStatus()` | `src/daemon/server.ts` | Status line → fields, `null` on anything unreadable |
+| `terminalCursorFrom()` | `src/daemon/server.ts` | Pane coordinates → frame coordinates (pure; `src/test/terminal-cursor.test.ts`) |
+| `syncCursor()` | `expo/components/TerminalPane.tsx` | Parks the block on the line it belongs to |
+
+Three things are less obvious than they look:
+
+**`cursor_y` is pane-relative; a frame is not.** `capture-pane -S - -E -`
+returns `history_size + pane_height` rows, so the visible pane is the *last*
+`pane_height` of them and the cursor's frame line is `rows − pane_height +
+cursor_y`. The pane's trailing blank rows are sent, not trimmed, and the
+client keeps them. They are what puts a cleared screen's prompt (^L, `clear`)
+at the top of the viewer, with the old screen scrolled into history above it,
+as in a real terminal; trimmed, the prompt sat at the bottom, right under the
+output it had cleared. Because the window is fitted to the smallest active
+viewer, the pane always fits, so those blank rows can never fill the view of
+someone scrolled to the bottom.
+
+**`cursor_flag` gates rendering.** An application that hides its cursor means
+it — Claude Code while a dialog is up, lazygit throughout — and a block drawn
+anyway is a caret the operator's real terminal doesn't show. Claude Code
+otherwise uses the *real* terminal cursor, so what tmux reports is Claude
+Code's cursor rather than an approximation of it.
+
+**A cursor moves when nothing else does.** Walking an arrow key along a shell
+input line repaints not one character, so the frame early-return would send
+nothing at all — precisely when a cursor is worth most. Position changes with
+unchanged content therefore get their own `{type: "cursor"}` message, outside
+the rAF frame coalescer, which exists to batch whole-screen work.
+
+Client-side, the block is a span parked **inside the line div it belongs to**,
+not positioned against the pane. It inherits that line's vertical position, so
+scrolling, alternate-screen centering and reflow are all correct for free, and
+the only thing computed here is `col × charWidth`. It paints with
+`mix-blend-mode: difference` over white, inverting the glyph underneath the way
+a real terminal does instead of covering it — which also means the client never
+has to know which character it is sitting on. Solid and blinking when this pane
+is where keystrokes land, hollow when they aren't: across split tabs and
+stacked routes, "which terminal am I typing into" is otherwise a guess.
+
+## Paste and copy
+
+Paste goes through a tmux **buffer**, never `send-keys`:
+
+```
+load-buffer -b brane-paste -   (text on stdin)
+paste-buffer -b brane-paste -p -t <nid>
+```
+
+`-p` is the point: it wraps the text in bracketed-paste markers *when the
+application asked for them*, so Claude Code sees 40 pasted lines as one paste
+rather than 40 submits, while a shell that doesn't do bracketed paste behaves
+exactly as it would under `tmux attach`. A buffer is also not bounded by argv
+(1 MB ceiling, `MAX_PASTE_BYTES`).
+
+Reaching the clipboard differs by platform, and all three paths converge on the
+socket's `paste` message:
+
+| Where | Path |
+|---|---|
+| Desktop | A document-level `paste` listener, behind the same two guards as keydown — the terminal is a `<pre>`, never an editable, so the event has no closer home |
+| Any platform chord | `isPasteChord()` makes keydown *step aside* for ⌘V (Mac) / ⌃V, ⌃⇧V (elsewhere). Swallowing ⌃V sent `C-v` to tmux and the browser never fired `paste`; ⌃V on a Mac stays quoted-insert |
+| Touch | The `^V 📋` keycap in the 🦾 controls menu (it took ^R's slot, so the quick bar fits phones narrower than a Max) reads the clipboard directly (a tap is the required gesture; iOS shows its own confirm chip). Mobile fires no `paste` event without a focused editable, so there is nothing for the listener to catch |
+| Touch, refused | A sheet with a real `<textarea>`, so the OS long-press → Paste menu works. The document listener catches that paste and closes the sheet |
+
+**Copy-out needs an escape hatch, because the mouse is spoken for.** In
+alternate mode every drag is forwarded as an SGR mouse event, which leaves no
+way to select a line. Holding **Option or Shift** suppresses forwarding and
+lets the browser select normally — the same convention Terminal.app and iTerm
+use when an application has grabbed the mouse — and the modifier also restores
+the context menu with its Copy item.
+
+## Block glyphs
+
+A mirror line is text in a line box pinned at `line-height: 1.4`, and a
+font's block glyph (`▀ ▄ █`) covers only its own ascent and descent, about
+14 px of a 16.8 px row. So block art was striped with a dark gap on every
+row, and `brane meld`'s half-block QR code came out looking like a barcode
+that scanned badly. The fix is on the client and nowhere else. `meld` prints
+the same bytes, so a real terminal is unaffected.
+
+`paintBlockGlyphs()` (`src/shared/block-glyphs.ts`, pinned by
+`src/test/block-glyphs.test.ts`) runs on each changed line after ansi_up. It
+wraps every U+2580–U+259F character in a span one cell wide and one line box
+tall, which paints the glyph as a background in `currentColor`, so SGR
+colors carry through. The character stays in the DOM, hidden with
+`-webkit-text-fill-color`, so copy still yields it. A line with no block
+element costs one regex test.
+
+**One full-cell image per glyph, never a sized layer.** The first cut
+painted each rectangle as a layer sized and positioned inside the cell, and
+left a hairline between lit rows. Each row starts on a fractional pixel, and
+each layer anti-aliased its own edge onto the shared boundary pixel. A
+full-cell gradient with hard stops (linear for bars, conic for quadrants)
+has the span's own edges, and the browser snaps those to whole pixels.
+
+## Launch residue in scrollback
+
+The mirror shows the pane's whole scrollback (`capture-pane -S -`), so
+anything a TUI drew and abandoned before the session settled is on screen for
+good. The case that prompted this section: a new fold opened under a stack of
+yellow `────` rules and three copies of "Accessing workspace". It was Claude
+Code's folder-trust dialog, redrawn at each width the window passed through:
+first created at `lastTerminalSize` (the last size applied to *any* session),
+then fitted to the viewer. Every stale frame went up into history, reflowed,
+its full-width rules now wider than the pane. The live screen was clean; the
+input box was pushed off the bottom only because the history above it was
+tall and wide.
+
+Two things address it, and neither touches the live screen:
+
+- **Start at the viewer's size.** The app remembers the grid its terminal pane
+  last measured (`lastTerminalSize()`, `expo/lib/terminal.ts`) and sends it as
+  `terminal_size` on `POST /api/spawn` and `POST /api/run`. The daemon starts
+  the tmux session at that grid when it is usable (`parseTerminalSize`,
+  `src/tmux.ts`, pinned by `src/test/terminal-size.test.ts`) and falls back to
+  `lastTerminalSize` otherwise, which is still what `brane spawn` from a shell
+  gets. A session that launches at the size it is watched at isn't resized
+  through a TUI's first screen.
+- **Clear scrollback, on request.** The 🦾 menu's last row, `Clear 🧽`, sends
+  `{ type: "clear_history" }` on the terminal socket; the daemon runs `tmux
+  clear-history` on the pane and forces a capture. The client trims to the
+  frame's `totalLines`, so the stale lines go with the next frame. It discards
+  history, so it is only ever the operator's explicit action, never automatic.
+
+A fold Claude has never been trusted in still shows the dialog once. Accepting
+it on the operator's behalf was considered and left for the operator to decide.