brane 0.1.1 → 0.3.1

package/docs/absorb.md

@@ -0,0 +1,231 @@
+# Absorb
+
+`brane absorb` imports conversation history from external LLM providers. Input is an **extracted export directory** (not a ZIP). `--fold` is required.
+
+The import runs **in the daemon**: `brane absorb` POSTs to `/api/absorb` and prints what comes back. `src/absorb/run.ts` holds the orchestration the CLI used to do in-process (`runAbsorb`), and the route streams its `AbsorbEvent`s as NDJSON — `info` lines for the pre-flight report, throttled `progress` lines the CLI renders as its `\r` counter, and a final `summary`; a failure after the stream has opened ends it with an `error` line, while anything the operator has to fix (unknown provider, missing directory, no identity, a fold the daemon would refuse) is refused as a plain 400/403 before the stream opens (`AbsorbInputError`, `FoldRegistrationError`) — a dry run checks the fold too, so it cannot pass a case the real run would fail. A successful import kicks off a memory indexing pass, not awaited, so search works right after it. The CLI resolves relative paths against its own cwd before sending, since the daemon's cwd means nothing to the operator; `~/…` is left for the daemon to expand. The organelle importer yields to the event loop between narratives so the daemon keeps answering — and so the progress lines actually reach the client mid-run.
+
+```bash
+brane absorb chatgpt <export-dir> --fold <fold-path> --dry-run  # preview
+brane absorb chatgpt <export-dir> --fold <fold-path>            # import
+```
+
+The absorb pipeline:
+1. Scans directory for conversation shards (`conversations-NNN.json`) + `user.json`
+2. Builds a file index mapping asset pointer IDs to local files
+3. Stream-parses each shard (one conversation at a time, low memory)
+4. Resolves image asset pointers → copies files to `~/.brane/payloads/`
+5. Extracts audio transcription text alongside string content parts
+6. Inserts conversations as archived narratives with `role: "absorbed"`
+
+`--dry-run` exercises all parsing and asset resolution without writing to the database.
+
+## Local sources
+
+The export providers above read a directory the operator asked a vendor
+for. A **local source** reads a session store an agent harness keeps on this
+machine, in place, and can be read again tomorrow. `brane absorb claude` is
+the first: `~/.claude/projects/<cwd>/<session>.jsonl`, the engineering
+half of a Claude user's history, already on the disk of anyone who has run
+`claude` once. It is the launch demo — one command and every Claude Code
+session ever run is searchable — and the reason `brane absorb survey`
+exists: a new user's first step is to be told what is there. A bare
+`brane absorb` prints usage, which names it.
+
+```bash
+brane absorb                          # usage, naming the providers and `survey`
+brane absorb survey                   # what this machine has, what an import would do
+brane absorb claude --dry-run         # the import, planned
+brane absorb claude                   # the import
+brane absorb claude --fold ~/dev/app  # only sessions run in that directory
+brane absorb claude --since 2w        # only sessions active recently
+brane absorb claude --session 3f1a    # one session, by id prefix
+brane absorb claude ~/backup/.claude  # a copied store instead of ~/.claude
+brane absorb claude --rebuild         # re-derive absorbed sessions nobody has written into
+```
+
+| Piece | Where | Does |
+|---|---|---|
+| `LocalSource` | `src/absorb/types.ts` | The seam: `locate` (is the store here), `identity`, `survey` (one cheap row per session — a stat and a head read, never message content), `extract` (the parse) |
+| `claudeCodeSource` | `src/absorb/claude-code.ts` | Survey and parser for Claude Code's JSONL |
+| `surveyAbsorbSources()` | `src/absorb/sources.ts` | The inventory behind `brane absorb survey` and `GET /api/absorb/survey`; also the `PROBES` — stores brane recognises but cannot read yet (codex, goose, copilot, gemini, cline, amp, Claude Desktop agent-mode), reported as *found, no extractor* so the operator learns what is there either way. The list is the tools brane spawns plus Claude Desktop, because those formats have been looked at, not because a source needs spawn support: an importer for a tool brane cannot run is welcome, the probes just aren't speculative (claude-xiy9e8wq:16, :17) |
+| `classifySessions()` | `src/absorb/sources.ts` | Each session as `managed` / absorbed-`unchanged` / absorbed-changed / `new`, shared by survey and import so the two cannot disagree. "Unchanged" means same size and mtime *and* read by a parser as new as this one |
+| `runLocalAbsorb()` | `src/absorb/run.ts` | The import: survey → select → classify → parse only what is new or changed |
+| `createAbsorbContext()` / `absorbOne()` | `src/absorb/index.ts` | The per-conversation *plan* and the write that follows it exactly; the ChatGPT stream feeds the same pair |
+
+Four things are less obvious than they look:
+
+**Idempotent per message, not per conversation.** The count-based append
+the ChatGPT path uses ("more messages than events → append the tail")
+cannot survive Claude's `--fork-session`, which copies a predecessor's
+records — ids included — into the successor's file. `absorb_messages` keys
+every written message by the provider's own id (`uuid`); a key already held
+is never written again, wherever it is read from. A successor file therefore
+lands as **only its new messages, the first of them `re` the predecessor's
+last** — a fork reads as a continuation, the same shape the twin protocol
+gives a live fork. A file that repeats another with nothing after it is not a
+narrative and is skipped. Sessions are absorbed oldest first so the
+predecessor's keys are always there before the successor asks (the cost
+backfill's ordering rule, for the same reason).
+
+**`--brane` is a destination, and destinations are independent.** Both
+ledgers and the absorbed-narrative lookup are keyed by brane as well as
+provider, so the same store imported into two branes is two complete
+copies, each with its own idempotent re-runs. The first cut keyed on
+provider alone, and a second brane saw every file as "unchanged" and read
+nothing (claude-xiy9e8wq:38); the provider-only rows were carried over by a
+migration that keeps the old tables as `_v1`. The survey answers for the
+brane a plain `brane absorb <source>` would target, the one derived from
+the account.
+
+**Sessions brane already owns are not imported** (claude-xiy9e8wq:13). A
+brane-spawned agent's session file sits in the same store as everyone else's.
+`classifySessions` marks a session `managed` when a live (non-absorbed)
+narrative of that agent type holds its id in `agent_session_id` or
+`session_ids`, and the import skips it and says so. Beneath that, the append
+path matches only `role = 'absorbed'` narratives, so nothing an import reads
+can ever be written into a live narrative's log. The agent-type filter is
+load-bearing, not an oversight: an ordinary `claude` run in a fold with a
+`.mcp.json` still bridges in, as an `external` narrative holding the session
+id, and it is deliberately *not* managed. That narrative is a participant
+that narrates almost nothing; the transcript is the only copy of the
+conversation, so skipping it would make the conversation unsearchable rather
+than deduplicated. The two coexist — the participant live in the home brane,
+the record absorbed into the account's.
+
+**Tool calls go to `tool_uses`, not into the text** (claude-xlolbv6l:65). A
+`tool_use` block becomes a row with `source: "absorb"` through the same
+`recordToolUse` the hooks use, keyed on the block's `toolu_…` id; the
+`tool_result` that follows supplies output, `failed` on `is_error`, and a
+duration from the two records' timestamps. `recordToolUse` grew an optional
+`afterSeq` for this: a hook's row belongs at the narrative's head because the
+call is happening now, an absorbed row belongs beside the message that made
+it. `thinking` blocks are not imported, and reasoning is not something
+absorb promises for any source: some tools withhold it, brane has nowhere
+to show it, it is far more text than a reader wants, and it reads as
+authoritative while being the part most likely to be wrong
+(claude-xiy9e8wq:20, :22). A narrative still never records itself: for a brane-managed session the whole
+file is skipped, so no `narrate`/`listen` row is ever written from a
+transcript.
+
+**A user turn is not always the operator's.** Claude Code writes its own
+text into `user` records, each kind in a tag, and read as prose the tags
+show through (claude-xiy9e8wq:29). Measured over one machine's store, by
+text block: 2,100 `<task-notification>` (a background task finished), 398
+`[Request interrupted by user]`, 17 `<command-name>` slash commands with
+their `<local-command-stdout>`, and 9 `<bash-input>`/`<bash-stdout>` pairs
+from `!` commands. `classifyUserBlock` gives each the rendering its meaning
+calls for, per block, so typed text beside an injected block keeps its own
+shape: a `!` command becomes `$ cmd` in a `sh` fence and its output a plain
+fence (stderr labelled), a slash command a code span, an interrupt an italic
+marker. A task notification is the completion of a call the agent made, not
+something the operator said, so it becomes a `tool_uses` row of its own
+(`name: task-notification`, keyed on the record uuid since one task can
+notify twice, `parent_id` the call's `toolu_…` id when the harness names it)
+and never enters the chat. Fences are sized past the longest backtick run
+inside them, so a captured code block cannot break out.
+
+**A message sent mid-turn is an attachment, and the attachment is the
+receipt** (claude-jdfccmvh:10). What the operator types while the agent is
+working is never written as a `user` record. The harness queues it
+(`queue-operation`: enqueue, then dequeue or remove), and when the running
+turn takes it in, writes an `attachment` of type `queued_command` at the
+point the agent read it — after the tool result it was waiting on, in the
+`parentUuid` chain — stamped with the time it was typed. Reading only `user`
+records dropped every such message, and left the record full of confident
+answers to questions it did not contain. `queuedTurnOf` reads the attachment
+and nothing else: `commandMode: "prompt"` is the operator's message,
+`"task-notification"` is a background task finishing by the same route and
+goes to `tool_uses` like its `user`-record twin, and an unknown mode is left
+out rather than guessed at. The queue-operation records are no second
+signal — older harness versions write `remove` with no reason for a
+delivery, and task notifications carry no `origin` — and none is needed: a
+message the operator cancelled (popped back into the editor) or that was
+never delivered has no attachment, so it stays out of the record as it
+stayed out of the conversation (claude-jdfccmvh:8). Measured on one
+machine's store: 450 attachments, 103 `prompt` and 347 `task-notification`;
+of 113 queued messages that never went through, none had one.
+
+**A pasted image is a payload** (claude-7irbudpw:52). Claude Code writes a
+pasted image into the `user` record itself, base64 in an `image` block
+beside its `[Image #N]` text; an image that arrives mid-turn is a
+`turnCompanion` record written the same way, with `isMeta` set and no text.
+The parser carries both as `attachments` on the message, the inline
+counterpart of the ChatGPT path's `assetPointers`, and the write decodes
+them into `~/.brane/payloads/<nid>/<time>_<seq>_<j>.<ext>` with the
+extension from the block's `media_type`, so the chat shows them inline
+through the payload route with no change on that side. A record with an
+image and no words becomes a message reading `(attachment)`, the placeholder
+the web app writes for an image-only signal, rather than falling to the
+empty-body guard; an `isMeta` record still contributes no text, only its
+images. Per-message idempotence covers the files: a message written once has
+its payloads written once. `createAbsorbContext` takes a `payloadsDir`
+override so the suite never writes under `~/.brane`. Not yet a payload: an
+image inside a `tool_result` (a `Read` of a `.png`), because `tool_uses` has
+no payload column; today that base64 lands in `output` under the capture cap.
+
+**A parser improvement reaches old narratives late, not out of order.**
+Events are append-only, so a record type the parser learns to read (#460's
+slash commands, the mid-turn messages above) has no key in `absorb_messages`
+and lands at the narrative's tail on the next ordinary re-run — after
+messages it preceded. `plan()` notices: a new message that belongs before
+something the narrative already holds is written `re` the held message it
+follows in the conversation (`lateFor`). It reads as late, it links to its
+place, and every `nid:seq` anyone has cited still says what it said. For
+the re-run to happen at all, `absorb_files` records which parser read each
+file (`LocalSource.parserVersion`): a finished session's file never changes
+again, so on (size, mtime) alone the improvement would reach it only through
+`--rebuild`. A file last read by an older parser is not "unchanged", and the
+next ordinary run reads it once more; the survey counts such files as their
+own bucket ("to re-read (newer parser)"), so a parser upgrade does not read
+as every absorbed file having changed. Bump the version when the parser
+learns to read something it used to skip. That is the default way a parser
+change reaches history; `--rebuild` is not. (Run over one machine's store
+for the mid-turn change: every absorbed session re-read, 0 of 11,812
+existing events altered, one recovered message landing `re` the narration it
+interrupted.)
+
+**`--rebuild` is the one deleting operation, and it deletes only a
+rendering.** It empties each selected narrative this brane has absorbed —
+events, tool rows, ledger rows, memory-index rows and cursor — and imports
+its file again: same narrative id and `created_at`, but **seqs from 1**, so
+the narrative still resolves and a `nid:seq` citation into it may now land
+on a different message; title refreshed; payload files left where they are
+and rewritten by name with the same bytes. It is allowed under the golden
+rule because the flag is the operator's explicit instruction and what is
+discarded is derivable from a file that is demonstrably still on disk (only
+survey candidates reach it). That holds only while the narrative is nothing
+but that rendering. An absorbed narrative can still be written into — a
+signal from the app, a foreign narration, a payload attached live — and
+none of that is in any file. So a narrative holding an event with no
+`absorb_messages` row (`liveContributions`) is **locked in**: `--rebuild`
+reads it as an ordinary re-run, which only appends, and reports it as "Not
+rebuilt" (claude-jdfccmvh:13). Talking in an absorbed narrative should be
+uncommon anyway — a conversation that wants to continue belongs in a
+`/twin`, which reads the record and leaves it alone (claude-jdfccmvh:15).
+The guard is in the SQL (`resetAbsorbedNarrative`): only `role =
+'absorbed'`, only this brane, only the narrative bound to that session id,
+and only one holding nothing but what an import wrote; a live narrative is
+never a candidate. Composes with `--fold`, `--since`, `--session` and
+`--dry-run`. `memory_content_df` is left alone; `brane memory index
+--rebuild` recomputes it. An ordinary re-run also refreshes a narrative's
+title from a grown file now, since the harness retitles as it goes.
+
+**No fold is registered.** Each session knows the directory it ran in, and
+that becomes the narrative's `fold_path`. Registering it too would call
+`registerFold` with the foreign brane id and *rebind* the operator's own
+`~/dev/x` to the absorbed brane, changing what `brane spawn` does there. So
+for a local source `--fold` is a **filter** ("sessions from this directory"),
+never a destination, and the survey reports directories as a count.
+
+What the survey promises a new user, and how it keeps it: nothing is read
+but a stat and the first 64 KB of each file (for `cwd` and the start time),
+nothing is imported until a source is named, and an import makes no network
+call — `src/absorb/` imports node builtins, better-sqlite3 and stream-json,
+and nothing else. The identity that names the brane comes from
+`~/.claude.json`'s `oauthAccount` (the account uuid, so one person's sessions
+from two machines share a brane), falling back to the OS user.
+
+Not yet a source, and each is one `LocalSource` away: Claude Desktop's
+agent-mode `audit.jsonl` (stream-json records, plaintext, tool lineage
+included), a claude.ai data export, and the codex/goose/copilot/cline stores
+whose readers `src/agents.ts` already has for resume and cost.

package/docs/cost-ledger.md

@@ -0,0 +1,125 @@
+# Cost Ledger
+
+Each narrative card shows a cumulative cost (`narratives.cost_amount` /
+`cost_unit`), sampled every 20 s for MCP-connected narratives from the
+harness's own usage log — a Claude JSONL, goose's SQLite, a codex rollout.
+Those logs belong to the harness, which may purge them, and `--fork-session`
+copies a predecessor's messages (ids included) into the successor's file. Both
+facts bear on the same question: *who gets credited for a message, and does
+the answer survive the file going away?*
+
+`usage_ledger` is the answer. The sampler writes what it read into the ledger
+and reads the narrative's total back **from the ledger**, never from the
+transcripts directly:
+
+| row kind | key | written by | rule |
+|---|---|---|---|
+| entry | `<agent>:<message id>` | adapters with `readUsageEntries` (claude) | `INSERT OR IGNORE` — the first narrative to insert a key keeps the credit |
+| session high-water | `session:<agent>:<session id>` | every other adapter, via its `readUsage` | `amount = MAX(old, new)` |
+
+The primary key is the dedup. A message fork-copied into a later session, or
+into another narrative, is a no-op on insert — and so is re-reading it after
+the file that originally held it has been purged, which is what the older
+"per-session totals that never decrease" idea got wrong: credit that is
+recomputed from whichever files survive *moves*, and a moved credit plus a
+frozen total is a double count. High-water rows are right for the harnesses
+that never share history between sessions (codex's counter restarts at zero on
+resume), because there is nothing there to mis-credit.
+
+Rows are never deleted, and never re-priced implicitly, so between
+re-pricings a ledger sum is monotonic by construction. Entry rows carry the
+`model` and token counts that priced them — so a deliberate re-pricing is
+possible as an explicit operation (see [Re-pricing](#re-pricing)), which is
+precisely what a purged transcript would have made impossible. `cost_amount` caches it, under one transition rule: a column
+value above the ledger sum is kept, since it was filled pre-ledger from
+transcripts that may already be gone. Id-less `<synthetic>` records key on
+their file position — unique and stable for an append-only transcript.
+Writes are skipped for a session whose transcript signature hasn't changed,
+so an idle session still costs one `stat` per tick.
+
+**A session can change under a running process.** Claude's id is assigned
+at launch (`--session-id`), but `/clear`, or `/resume` from inside a session,
+moves the same process to a new transcript under an id Claude Code mints
+itself. The bridge read `CLAUDE_CODE_SESSION_ID` once at startup and `/clear`
+doesn't restart MCP servers, so nothing reported it: one narrative's card sat
+at $5.52 while $26.97 went unread, and revive would have resumed the
+conversation from before the `/clear`. Each live tick therefore runs
+`maybeFollowLiveSession`, which asks the adapter's `liveSessionId` and, on a
+change, retires the old id into `session_ids` and moves the pointer. Claude's
+answer comes from `~/.claude/sessions/<pid>.json` for the pane's own pid
+(`src/claude-live-session.ts`), accepted only if its `pid`, `tmux` session,
+`cwd` and `startedAt` (no earlier than the latest spawn or revive) all match.
+It is a pull from the one process whose record it is, deliberately not a hook
+payload or bridge report: everything in the pane inherits the narrative's bind
+secret, including a nested `claude -p`, and a subagent or reconnecting bridge
+must have no way to move the pointer. A narrative whose pane is already gone
+is not followed; its missed session reaches the ledger only if it is added to
+`session_ids` and backfilled.
+
+The 20 s sampler covers MCP-connected narratives plus a 120 s **linger** after
+a narrative's last bridge closes — a session's final turns are written to the
+transcript *after* MCP teardown, and the linger's few extra ticks are what
+catch them. The linger set is in-memory, so a disconnect that straddles a
+daemon restart is missed; that case — and every session that ended before the
+ledger existed — reaches the ledger through **`brane cost backfill`**
+(`POST /api/cost/backfill`). It runs in the daemon, like spawn and revive,
+because the readers resolve transcripts against the daemon's HOME. It walks
+narratives **oldest first**, which is what makes the credit assignment right:
+an original must insert its messages before the twin that forked from them.
+It is synchronous on the daemon's only thread — a cold pass over this
+fold's transcripts is a few seconds — which is fine for a command the
+operator runs and the reason it must never be wired to startup. It does
+not run session-id discovery — fold+time matching against years of
+history could adopt a transcript that was never the narrative's — so only
+already-bound sessions are read. `--dry-run` reports the same per-narrative
+lines (`readable/bound sessions`, rows and amount it would add, column before
+→ after) without writing; a second real run reports 0 changed.
+
+## Re-pricing
+
+`src/cost/pricing.ts` is a substring-keyed table, first match wins, and a
+price change reaches the ledger only through **`brane cost reprice`**
+(`POST /api/cost/reprice`, `src/cost/reprice.ts`). It re-prices every USD
+entry row that has a model and token counts under the current table,
+**moves each affected narrative's `cost_amount` by the same delta**, and
+broadcasts the new totals. `--dry-run` computes the identical result and
+writes nothing. The operator runs it; it is never wired to startup.
+
+| Piece | Where | Does |
+|---|---|---|
+| `DEFAULT_PRICES` | `src/cost/pricing.ts` | The table. A specific key (`fable-5-1`, `opus-5-5`, `sonnet-5`) sits above its family key, and an entry names its own `cacheRead` when it isn't 0.1× input. Rates last checked against the published pricing page on 2026-09-23 |
+| `pricing.json` | `~/.brane/` | Operator overrides, matched **before** the defaults. Appended after them, as they once were, an override for `opus-5-5` could never beat `opus` |
+| `LEGACY_PRICES_V1` | `src/cost/pricing.ts` | The table before 2026-09-23, frozen. Never edit it: it describes rows that already exist |
+| `recoverCacheWrite1h` | `src/cost/reprice.ts` | The 5-minute / 1-hour split of an old row's `cache_write` |
+| `cache_write_1h`, `speed` | `usage_ledger` | Recorded on every new row, so later reprices never have to infer |
+
+Three things are less obvious than they look:
+
+**Old rows lost the cache split, and the amount gives it back.** Rows
+written before `cache_write_1h` existed hold 5-minute and 1-hour writes as
+one count, and those bill at 1.25× and 2× input. But each amount was
+computed by a known table from exactly those tokens, so pricing every write
+as 5-minute undershoots it by `0.75 × input × (1-hour tokens)`. A recovered
+split is accepted only if it is a whole number of tokens in `[0,
+cache_write]` that reproduces the recorded amount. Anything else (a row
+priced under an override, say) is reported as unrecoverable and left as
+recorded. The first reprice writes the split it recovers. On this machine's
+ledger, all 24,075 priced rows recovered.
+
+**The card total moves by the correction; it is not reset to the ledger
+sum.** A `cost_amount` above its ledger sum holds pre-ledger cost from
+transcripts that may be gone, which is why the sampler keeps it. A reprice
+that reset the column would discard that. One that only lowered ledger rows
+would change nothing on the card, because the column already sits above the
+new sum.
+
+**Fast mode is a multiplier, not a table.** `usage.speed === "fast"` bills
+every category at 2× the model's standard rate, with the cache multipliers
+on top ($8/$40 on Opus 5.5, $10/$50 on Opus 5 and 4.8). The table can't
+express `inference_geo: "us"` (1.1×) or web search ($10 per 1,000). Neither
+appears in a transcript here yet.
+
+The first run corrected what three mispriced models had recorded: Fable 5.1
+cache reads at 4× the published rate, Opus 5.5 at the general Opus rate,
+and Sonnet 5 at Sonnet 4.x's. On a copy of the operator's database that was
+4,906 rows over 70 narratives, $4,576.26 → $3,852.50.

package/docs/daemon-api.md

@@ -0,0 +1,189 @@
+# Daemon
+
+The daemon serves HTTP API + WebSocket endpoints + the Expo web app as static files.
+
+```bash
+node dist/cli.js daemon start        # Background (detached)
+node dist/cli.js daemon start --foreground
+node dist/cli.js daemon restart      # Preserves port across restarts
+node dist/cli.js daemon status       # Shows pid, port, and the socket this machine's CLI uses
+node dist/cli.js daemon logs -f      # Tail logs
+```
+
+## HTTP API Endpoints
+
+All endpoints require `Authorization: Bearer <token>` (or `?token=`), except
+a request over `daemon.sock`, which presents none and acts as this account.
+
+**Agent tokens reach less.** A request made with an agent's token is refused
+(403) unless its route is listed in `AGENT_ROUTES`
+(`src/daemon/agent-scope.ts`), and unless it comes over `daemon.sock` or
+loopback; WebSocket upgrades too. A new route is therefore closed to agents
+until someone lists it. An agent also may not revive or prompt a
+`utility` session (`POST /api/run`). See [Agent tokens](token-rotation.md#agent-tokens).
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/api/status` | Daemon status (brane_id, hostname, username, pid, port, uptime_ms, `tls: { state, expires_at, ... }`, `app_domain`: the shared app's host, where a daemon's own bundle hops out to on Isolate — see [View URLs](view-urls.md)) |
+| `GET` | `/api/narratives?archived=1` | List narratives (excludes archived by default) |
+| `GET` | `/api/narratives/recent?since=&search=&status=&fold=&limit=&archived=1&brane_ids=` | Recently active narratives — the browse half of the `narrative_info` MCP tool; every brane unless `brane_ids` scopes it |
+| `PATCH` | `/api/narratives/:id/archive` | Archive/unarchive a narrative |
+| `GET` | `/api/narratives/:id/events?after=N&before=S&tail=T` | Fetch events with cursor-based query |
+| `POST` | `/api/narratives/:id/signal` | Send operator signal (supports payloads). `source` is stamped from the token (`web` for a device, `local` for this account); a `source` in the body is ignored, and an agent's token is refused (`src/daemon/signal-source.ts`) |
+| `GET` | `/api/narratives/:id/export?format=html[&palette=N][&seqs=A,B,C][&seqs_mode=except]` | Conversation as a standalone HTML document; `palette` is the device's 🎨 Recolor salt, so foreign speakers wear the hues the operator sees, `seqs` is the chat's message selection, and `seqs_mode=except` exports its complement — see [Export Scope](export-scope.md) |
+| `GET` | `/api/payloads/:nid/:filename` | Serve stored payload files (immutable, cached) |
+| `GET` | `/api/branes` | List branes with narrative counts, home flag, and `cost: [{ unit, amount, metered }]` — per-unit running totals over every narrative, archived included |
+| `GET` | `/api/folds?archived=1` | List registered fold directories (includes brane_id; archived hidden unless asked) |
+| `POST` | `/api/folds` | Register a fold (`{ path, brane_id? }`) — idempotent; see [Folds API](#folds-api) for who may register what |
+| `PATCH` | `/api/folds/archive` | Soft-hide/unhide a fold (`{ path, archived }`) — never deletes the row |
+| `POST` | `/api/spawn` | Spawn agent (`{ agent, fold_path, role?, model?, re?, extra_args?, terminal_size? }`) — used by both the web app and `brane spawn` |
+| `GET` | `/api/spawn-history` | Recent distinct `launch_args`, most-recent first (spawn dialog quick-fill) |
+| `POST` | `/api/run` | Run non-agent command (`{ command, fold_path, terminal_size? }`) |
+| `GET` | `/api/run-history` | Commands utility sessions have run before (by basename), most-recent first — the spawn dialog's Utility list; derived from `narratives`, nothing stored |
+| `POST` | `/api/revive/:nid` | Revive a dead agent session (`{ prompt?, no_prompt?, agent? }`) — see [Revive API](#revive-api) |
+| `POST` | `/api/search` | Semantic search over narrative history (`{ query, limit?, brane_ids? }`) |
+| `POST` | `/api/cost/backfill` | Sweep the usage ledger over every narrative with a bound session (`{ dry_run? }`) — see [Cost Ledger](cost-ledger.md) |
+| `POST` | `/api/cost/reprice` | Re-price recorded ledger rows under the current price table and move each card total by the correction (`{ dry_run? }`) — see [Re-pricing](cost-ledger.md#re-pricing) |
+| `POST` | `/api/tokens` | Mint a device token (`{ label? }` → `{ token, id, label }`); only its hash is kept, so this response is the one copy. `brane meld` calls it for every QR — see [Token Rotation](token-rotation.md). From the shell it waits for the [presence check](presence.md#the-gate) (403, 409 or 429 when refused); an agent's token gets 403 unasked |
+| `POST` | `/api/tokens/remote` | A device token for a daemon on another machine, and its hash (`{ token, hash }`), for `brane meld --remote`; nothing is stored, so this response is the one copy of either. Gated like `POST /api/tokens`: the shell waits for the [presence check](presence.md#the-gate), an agent's token gets 403 unasked |
+| `GET` | `/api/tokens` | The Devices list: every live token (`{ tokens }`), each with `device` ("Safari on iPhone", from the User-Agent it was first presented with), `remote_addr`, the latest sighting and `elsewhere_at` (presented from a second address), `minted_by_device`, `last_used_at`, `current` (the requester), `connected`, and `unused` / `expires_at` for a QR nobody has scanned — see [Token Rotation](token-rotation.md#the-devices-list) |
+| `POST` | `/api/tokens/:id/revoke` | Revoke one device token, bodiless, plus `?also=a,b` from the devices it added (each row's `descendants`); every socket it opened (control, terminal, MCP) closes with 4401. Refuses this machine's own `local` row (400), the requester's own (409), and an id that is not live (404), all before any prompt. Signing out a device waits for the [presence check](presence.md#the-gate) from the shell and is refused (403) to an agent's token; revoking an agent does neither |
+| `POST` | `/api/token/rotate` | From a device: mint a pending replacement token, returned as `{ token, expires_at, replaced }`; the old one is retired on the new one's first use — see [Token Rotation](token-rotation.md). From this machine's shell (no token, over `daemon.sock`): wait for the [presence check](presence.md#the-gate), then sign out every device in this one request, answering `{ signed_out, replaced }`. An agent's token gets 403 |
+| — | `BRANE_DEVICE_TOKEN_SHA256` | Not a route: comma-separated SHA-256 hashes in the daemon's environment, each adopted at startup as a device row unless ever seen before, then dropped from the environment. How `brane meld --remote` hands a remote daemon (a Fly machine, say) a token minted elsewhere — see [Presence Check](presence.md#the-gate) |
+| `POST` | `/api/presence/cancel` | Close the presence prompt that is up (`?id=` from the control socket's `presence` message, so a stale tap closes nothing) → `{ canceled }`. Device tokens only (403 otherwise); there is no approve |
+| `GET` | `/api/absorb/survey` | Every session store brane can look for under the daemon's HOME, with per-session `new / changed / unchanged / managed` counts for the readable ones and a found-flag for the rest; reads no content — see [Absorb](absorb.md) |
+| `POST` | `/api/absorb` | Import conversation history (`{ provider, path?, fold?, identity?, brane?, dry_run?, since?, session?, rebuild? }`); answers as an NDJSON progress stream — see [Absorb](absorb.md) |
+| `POST` | `/api/memory/index` | Run a memory indexing pass (`{ rebuild? }`), queued behind the daemon's own background pass; returns `IndexStats` |
+| `GET` | `/api/files?nid=<nid>&path=<rel>[&raw=1][&offset=N]` | Browse a narrative's fold, archives included — see [Files API](files-view.md#files-api) and [Files View Formats](files-view.md#files-view-formats) |
+| `GET` | `/api/files/list?nid=<nid>` | Flat list of every file path under the fold (for fuzzy find) |
+| `GET` | `/api/files/find?nid=<nid>&path=<rel>&q=<query>[&from=N]` | Search a file's bytes for the hex view's 🔎, as an NDJSON stream — see [Searching the bytes](files-view.md#searching-the-bytes) |
+| `POST` | `/api/highlight` | Shiki-highlight a snippet (`{ content, lang }`) — used by chat code blocks |
+| `POST` | `/api/diagram` | Render a ```mermaid fence to static SVG (`{ source }`) — `{ diagram: null }` means "not a diagram brane draws" and is a normal answer |
+| `POST` | `/api/wiki/search` | Semantic search over wiki pages (`{ query, limit?, brane_ids? }`) — see [Wiki: Local and Shared](wiki.md) |
+| `GET` | `/api/wiki/read?slug=&source=&anchor=&window=` | Read a wiki page or one section with heading neighbors |
+| `GET` | `/api/wiki/asset?source=&path=` | Serve a binary asset from a wiki source dir (traversal-confined) |
+
+## WebSocket Endpoints
+
+| Path | Purpose |
+|------|---------|
+| `WS /ws/control` | Real-time control channel (event hints, signals, status/meta broadcasts) |
+| `WS /ws/terminal/:nid` | tmux terminal mirroring (capture-pane at 10fps) |
+| `WS /ws/mcp?nid=<id>` | MCP tool bridge (daemon owns all tool logic) |
+
+Control WebSocket broadcasts (server → client):
+- `state` — initial state with all narratives
+- `new_events` — event count hints for a narrative
+- `status` — narrative status changes (active, ended, mcp_connected, mcp_disconnected)
+- `awaiting` — `{ narrative, awaiting }`: the agent parked in a blocking `listen` or a `narrate({ wait: true })`, or stopped waiting (`src/daemon/awaiting.ts`). The app shows it as an inset glow on the list card, switcher row and header (`awaitingGlow`, `src/shared/narrative-status.ts`), in a hue this device allocates: chosen once, as far as possible from the other recently glowing narratives' hues, then kept so sessions can be learned by color; 🎨 Recolor moves it to a random hue at least 100° away, so a press changes the color family rather than shading it, and at least 60° from the hues it was recolored away from in the last hour, so repeated presses explore rather than toggle. It stays clear of the other sessions' hues where the wheel allows; when crowded, that clearance gives way before the step or the return does (`src/shared/glow-hues.ts`, `localStorage` only). Its own message type, not a `status`, so an older app ignores it
+- `meta` — narrative metadata updates (summary, title)
+- `heartbeat` — 30-second keepalive
+
+Control WebSocket commands (client → server):
+- `signal` — send signal to a narrative (with payload support); stamped and refused as `POST /api/narratives/:id/signal` is, with a refusal answered by a `signal_refused` frame
+- `subscribe` / `unsubscribe` — narrative event subscriptions
+
+## Spawn API
+
+`POST /api/spawn` accepts `{ agent, fold_path, role?, model?, re?, extra_args?, terminal_size? }` and returns the new narrative object with `mcp_connected` status. `terminal_size` (`{ cols, rows }`) is the grid the requesting viewer's terminal pane last measured; the session starts at it rather than at the last size applied to any session, so its first screen is not redrawn through a resize — see [Launch residue in scrollback](terminal-mirroring.md#launch-residue-in-scrollback). `/api/run` takes it too. The fold picker modal lets the operator choose which registered fold to spawn into. The dialog's Agent list is the built-in adapters plus an "Other…" entry that takes any agent name, as `brane spawn <agent>` does: the daemon accepts any `[A-Za-z0-9_-]+` name it can find with `which`, and an agent without an adapter gets tmux, MCP config and mirroring but no session resumption. What is typed there splits like the args box, so the first word is the agent and the rest lead its `extra_args`.
+
+This is the **only** spawn path. The web UI calls it, and so does `brane spawn` — the CLI resolves a daemon (starting one if needed), POSTs here with `fold_path` set from `cwd` and `-- <args>` as `extra_args`, and then does only terminal-shaped work with the response: `--meld`'s QR code and `--attach`. It does not open the database or create tmux sessions itself, so tmux bootstrap (`ensureTmux`), terminal sizing, and MCP config writing happen once, daemon-side, identically for both callers. Two consequences follow from that and are intended: the agent binary is resolved against the *daemon's* `PATH`, and MCP config files point at the checkout the *daemon* runs from — not the CLI you invoked.
+
+`src/daemon/client.ts` is the CLI-side counterpart to `daemon/server.ts`: `resolveDaemonEndpoint()` (find-or-start, and pick a locally reachable origin — under TLS that means the HTTP fallback port, since the Tailscale cert is never valid for `127.0.0.1`) plus `daemonRequest()` (bearer auth, JSON, rethrows the daemon's own `error` string).
+
+## Revive API
+
+`POST /api/revive/:nid` accepts `{ prompt?, no_prompt?, agent? }` and returns `{ status, nid, agent }`. It is the **only** revive path — the web app's revive menu item, the `revive` MCP tool, and `brane revive` are all clients of it, in the same shape as the Spawn API above. The CLI resolves a daemon, POSTs, and prints; it does not open the database, resolve adapters, or create tmux sessions.
+
+`status` is the outcome, and clients must not assume `nid` is the one they asked for:
+
+| `status` | Meaning |
+|---|---|
+| `revived` | The session was dead and has been restarted in place, resuming its agent session (Claude forks with `--fork-session` when the original is still live). |
+| `already_running` | tmux still had the session. A `prompt` is delivered if given; a stale `ended` row is self-healed to `active` and broadcast. |
+| `continued` | The narrative can't be resumed in place — it was absorbed, or `agent` names a different agent — so a **twin** was spawned that reads its history. `nid` is the twin's, not the requested one. |
+
+## The CLI is a daemon client
+
+Spawn and revive set the pattern; the rest of the CLI follows it. A command
+that touches narratives, folds, sessions, or the memory index does so by
+calling the daemon, and keeps only terminal-shaped work for itself — resolving
+the operator's relative paths against *this* shell's cwd, printing, attaching
+to tmux. The reasons are the ones the Spawn API section gives, and one more
+that absorb makes concrete: every path the pipeline resolves — payloads, the
+organelle `search.db`, the niche registry — resolves against **the daemon's
+HOME**, and two processes indexing the same cursors (the daemon's background
+pass and an in-process `brane memory index`) was a race nobody had to have.
+
+| Command | Calls |
+|---|---|
+| `spawn`, `revive` | `POST /api/spawn`, `/api/revive/:nid` |
+| `list` | `GET /api/narratives`, `GET /api/branes` |
+| `fold` | `POST /api/folds`, `GET /api/folds?archived=1` |
+| `absorb` | `GET /api/absorb/survey`, `POST /api/absorb` — an NDJSON stream, read with `daemonStream()` |
+| `memory log` / `search` / `index` | `GET /api/narratives/recent`, `POST /api/search`, `POST /api/memory/index` |
+| `cost backfill` / `reprice` | `POST /api/cost/backfill`, `POST /api/cost/reprice` |
+| `token list` | `GET /api/tokens` |
+| `token revoke <id>` | `POST /api/tokens/:id/revoke` |
+| `token rotate` | `POST /api/token/rotate` (one request: the shell holds no token to swap) |
+
+**How it gets there: `daemon.sock` first.** The daemon also listens on a
+Unix socket beside the database (`~/.brane/daemon.sock`, recorded as
+`meta.daemon_socket`; `src/daemon/local-socket.ts`), with the same request
+and upgrade handlers. `daemonRequest()` and `daemonStream()` send over it
+when it is there. Inside an agent session, which has a token to present,
+they fall back to TCP at `buildDaemonBaseUrl()` when the socket
+cannot be connected to — any failure before it connects, so nothing was
+sent; a failure after that is reported, never retried, so a POST cannot run
+twice. Outside one there is nothing to present over TCP, so there is no
+fallback: the socket is the only way in, and the error says so. `brane mcp` dials `ws://localhost/ws/mcp` with `createConnection` to
+the socket (`mcpDialTarget()`), keeping the path out of the URL, and uses
+TCP whenever the socket does not answer a probe at (re)connect. Reaching the socket takes search permission on the
+0700 `~/.brane`, so the kernel admits only this Unix account (and root),
+which loopback TCP cannot promise. So a request over it that presents **no
+token** acts as this account: the live `local` row ("this machine"), with
+the same last-seen bookkeeping a presented token gets
+(`authenticateRequest()` in `server.ts`, `TokenStore.account()`). That holds
+only while `~/.brane` is owned by the daemon's uid with no group or other
+bits (`accountDirTrust()`), checked on every such request, since both
+chmods that set it up swallow their errors; otherwise the request is
+refused and the daemon logs why, once per reason until one is let in again.
+A tokenless request with an `Origin` header, or a `Host` other than
+`localhost`, is refused too: the CLI and bridge send neither, and that is
+the shape of a browser's request arriving through a relay to the socket.
+An empty token counts as none. No token over TCP, even
+loopback, is refused as before. A client sends a token only inside an
+agent session (`resolveCredential()`); everything else on this machine sends
+none, over the socket, and never falls back to TCP, where it would only be
+a 401. No client reads `.daemon_token`, which older branes kept a local
+token in — see [No local token](token-rotation.md#no-local-token).
+A crashed daemon leaves its socket file behind; the next one, once
+it holds the claim, removes it only if it is a socket whose connect is
+refused (`ECONNREFUSED`), and otherwise leaves the path alone; until it is
+cleared, agents and devices are served over TCP and this machine's shell,
+which holds no token, cannot reach the daemon (`brane doctor` says why).
+
+What stays local is what must: `daemon` *is* the daemon; `mcp` is the bridge
+into it; `config` is how `token` and `default.brane` are set before a daemon
+exists (and the daemon itself reads them through `getConfig`); `certify`
+writes the cert files the daemon hot-reloads; `doctor` is a diagnostic and
+must not depend on the thing it diagnoses; `attach` is tmux; `meld` already
+finds-or-starts the daemon and reads two `meta` rows to build a URL.
+
+Every client calls `warnIfVersionMismatch()` first, because a request field
+this CLI knows about is silently ignored by an older daemon. A new
+source-reading habit to resist: a command that wants a new fact should get it
+from a route (adding one if needed), not from `openDatabase()` — the moment a
+command opens the database it has a second implementation to keep in step.
+
+## Run API
+
+`POST /api/run` accepts `{ command, fold_path }` where `command` is an array of strings. Creates a tracked tmux session for non-agent processes (lazygit, htop, etc.) with terminal mirroring but no MCP, LIVE loop, or agent adapter. The narrative gets `role: "utility"` and `agent_type` set to the command basename. The spawn dialog reaches it through its **Utility** side (the label opposite **Agent**), whose list is `GET /api/run-history` plus an "Other…" entry for a command never run before. The dialog is its only client: the `brane run` CLI command was retired (2026-10-10). A utility session's environment carries no agent token, so it is this account's standing in one call, and the route is closed to agents (`src/daemon/agent-scope.ts`); the CLI command added nothing the dialog lacks (same route, same env scrubbing, no env passthrough from the calling shell), and keeping it kept a `brane` verb in every agent's shell whose only job was to start such a session. `brane attach <nid>` attaches to one the app started.
+
+## Folds API
+
+`GET /api/folds` returns registered fold directories sorted by `created_at` descending, archived ones only with `?archived=1`. Used by the Expo app to populate the spawn fold picker.
+
+`POST /api/folds` with `{ path, brane_id? }` registers one — the app's "add a spawn point" affordance and `brane fold` are both clients — and returns `{ fold, created }`. It is idempotent: re-registering un-archives the row and, with `brane_id`, rebinds it (`brane fold --brane`, and absorb tagging a fold with the brane it imports into). The implementation is `registerFold` in `src/folds.ts`, shared with absorb.
+
+**Who may register what.** A phone on the tailnet must not be able to make `/` or `/etc` a spawn point, so a remote client's folds are confined to the operator's home directory (403 outside it, and for `$HOME` itself). The operator's own shell has never been so limited — `brane fold /Volumes/scratch/project` has always worked — and now that the CLI reaches this through the daemon, that reach is recognized on the wire as **loopback**: `isLoopbackRequest()` in `src/daemon/server.ts` grants it to a connection on `daemon.sock` and to `127.0.0.0/8` and `::1`, which is what the CLI dials (`daemon.sock`, else `buildDaemonBaseUrl`) and what nothing off this machine can. The one gap is the TLS window where the fallback port isn't recorded yet and the CLI dials the Tailscale hostname; it lasts about a second after daemon start and the request is then simply confined. `foldPathRefusal()` is the pure decision, pinned by `src/test/thin-cli.test.ts`. Read the rule as a guard against **mistakes**, not a security boundary: the token already grants keyboard input to every tmux session, so a holder who wanted `/etc` could have it; what the rule prevents is a phone's file picker or a typo quietly making the wrong directory a spawn point. That is also why `POST /api/absorb` confines the *fold* it registers but not the export *path* it reads.