brane 0.0.2 → 0.3.0

package/expo/dist/sw.js

@@ -0,0 +1,154 @@
+// Brane service worker — cache-first for static assets, network-first for API/WS.
+//
+// The two constants below are placeholders in this source file and are rewritten
+// in `dist/sw.js` by scripts/gen-precache.mjs, which reads the export that was
+// actually produced. Editing them here has no effect on a build; see that script
+// for why the list is generated rather than maintained by hand.
+const CACHE_NAME = "brane-420ad94d3632";
+const PRECACHE = [
+  "/",
+  "/_expo/static/js/web/entry-e56efc1291dca7258ea00b8108b033a4.js",
+  "/assets/node_modules/@react-navigation/elements/lib/module/assets/back-icon-mask.0a328cd9c1afd0afe8e3b1ec5165b1b4.png",
+  "/assets/node_modules/@react-navigation/elements/lib/module/assets/back-icon.35ba0eaec5a4f5ed12ca16fabeae451d.png",
+  "/assets/node_modules/@react-navigation/elements/lib/module/assets/clear-icon.c94f6478e7ae0cdd9f15de1fcb9e5e55.png",
+  "/assets/node_modules/@react-navigation/elements/lib/module/assets/clear-icon.c94f6478e7ae0cdd9f15de1fcb9e5e55@2x.png",
+  "/assets/node_modules/@react-navigation/elements/lib/module/assets/clear-icon.c94f6478e7ae0cdd9f15de1fcb9e5e55@3x.png",
+  "/assets/node_modules/@react-navigation/elements/lib/module/assets/clear-icon.c94f6478e7ae0cdd9f15de1fcb9e5e55@4x.png",
+  "/assets/node_modules/@react-navigation/elements/lib/module/assets/close-icon.808e1b1b9b53114ec2838071a7e6daa7.png",
+  "/assets/node_modules/@react-navigation/elements/lib/module/assets/close-icon.808e1b1b9b53114ec2838071a7e6daa7@2x.png",
+  "/assets/node_modules/@react-navigation/elements/lib/module/assets/close-icon.808e1b1b9b53114ec2838071a7e6daa7@3x.png",
+  "/assets/node_modules/@react-navigation/elements/lib/module/assets/close-icon.808e1b1b9b53114ec2838071a7e6daa7@4x.png",
+  "/assets/node_modules/@react-navigation/elements/lib/module/assets/search-icon.286d67d3f74808a60a78d3ebf1a5fb57.png",
+  "/assets/node_modules/expo-router/assets/arrow_down.017bc6ba3fc25503e5eb5e53826d48a8.png",
+  "/assets/node_modules/expo-router/assets/error.d1ea1496f9057eb392d5bbf3732a61b7.png",
+  "/assets/node_modules/expo-router/assets/file.19eeb73b9593a38f8e9f418337fc7d10.png",
+  "/assets/node_modules/expo-router/assets/forward.d8b800c443b8972542883e0b9de2bdc6.png",
+  "/assets/node_modules/expo-router/assets/pkg.ab19f4cbc543357183a20571f68380a3.png",
+  "/assets/node_modules/expo-router/assets/sitemap.412dd9275b6b48ad28f5e3d81bb1f626.png",
+  "/assets/node_modules/expo-router/assets/unmatched.20e71bdf79e3a97bf55fd9e164041578.png",
+  "/favicon.svg",
+  "/katex/fonts/KaTeX_Main-Bold.woff2",
+  "/katex/fonts/KaTeX_Main-BoldItalic.woff2",
+  "/katex/fonts/KaTeX_Main-Italic.woff2",
+  "/katex/fonts/KaTeX_Main-Regular.woff2",
+  "/katex/fonts/KaTeX_Math-BoldItalic.woff2",
+  "/katex/fonts/KaTeX_Math-Italic.woff2",
+  "/katex/katex.min.css",
+  "/manifest.json"
+];
+const VENDOR_CACHE = "brane-vendor-d57f3df64e26";
+
+// Vendored files fetched on demand rather than precached: KaTeX's font tail and
+// pdf.js. They go in a cache of their own, named for a hash of the vendored
+// files alone, because CACHE_NAME changes on essentially every build — and
+// `activate` drops every cache but the current ones. Kept in CACHE_NAME, a face
+// fetched last week was gone after the next deploy, so "updated while online,
+// then went offline" rendered math in fallback glyphs. Here they survive every
+// build that doesn't change the vendored files themselves, and a KaTeX or
+// pdf.js upgrade retires them together.
+function isVendor(pathname) {
+  return (
+    pathname.startsWith("/katex/") ||
+    pathname === "/pdf.min.mjs" ||
+    pathname === "/pdf.worker.min.mjs"
+  );
+}
+
+// Assets safe to serve from cache without revalidating. `_expo/static` is
+// content-hashed; the rest are vendored files that only change with a build,
+// which is also when CACHE_NAME changes and the old cache is dropped.
+function isStatic(pathname) {
+  return (
+    pathname.startsWith("/_expo/static/") ||
+    pathname.startsWith("/assets/") ||
+    pathname.startsWith("/katex/") ||
+    pathname === "/favicon.svg" ||
+    pathname === "/manifest.json" ||
+    // pdf.js is deliberately left out of PRECACHE (1.7 MB); this is what makes
+    // it stick after the first PDF you open.
+    pathname === "/pdf.min.mjs" ||
+    pathname === "/pdf.worker.min.mjs"
+  );
+}
+
+// Precache the shell on install. `addAll` is atomic on purpose: a partial
+// precache is the silent half-offline state this worker exists to eliminate, so
+// a failed install leaves the previous worker serving and retries on next load.
+self.addEventListener("install", (event) => {
+  event.waitUntil(
+    caches
+      .open(CACHE_NAME)
+      .then((cache) => cache.addAll(PRECACHE))
+      .then(() => self.skipWaiting()),
+  );
+});
+
+self.addEventListener("activate", (event) => {
+  // Clean old caches — every one but this build's shell and the vendored files
+  // it ships, which may well be the same files an older build fetched.
+  event.waitUntil(
+    caches.keys().then((keys) =>
+      Promise.all(
+        keys.filter((k) => k !== CACHE_NAME && k !== VENDOR_CACHE).map((k) => caches.delete(k)),
+      )
+    ).then(() => self.clients.claim())
+  );
+});
+
+function cacheFirst(request, cacheName) {
+  return caches.match(request).then((cached) => {
+    if (cached) return cached;
+    return fetch(request).then((response) => {
+      if (response.ok && !isShellFallback(response)) {
+        const clone = response.clone();
+        caches.open(cacheName).then((cache) => cache.put(request, clone));
+      }
+      return response;
+    });
+  });
+}
+
+// None of the static paths is HTML, but the servers answer a path they don't
+// have with the SPA shell and a 200 — the daemon's static handler and the
+// Cloudflare worker's single-page fallback both do. A font or script URL
+// requested mid-deploy (an `expo export` clears its output first) would cache
+// that page under its own name, cache-first, never revalidated. In
+// VENDOR_CACHE it would then outlive every build until KaTeX or pdf.js
+// changed. So an HTML answer to a static request is served, never kept.
+function isShellFallback(response) {
+  return (response.headers.get("content-type") || "").toLowerCase().startsWith("text/html");
+}
+
+self.addEventListener("fetch", (event) => {
+  const url = new URL(event.request.url);
+
+  // Skip non-GET, API calls, and WebSocket upgrades
+  if (
+    event.request.method !== "GET" ||
+    url.pathname.startsWith("/api/") ||
+    url.pathname.startsWith("/ws/")
+  ) {
+    return;
+  }
+
+  if (isStatic(url.pathname)) {
+    event.respondWith(cacheFirst(event.request, isVendor(url.pathname) ? VENDOR_CACHE : CACHE_NAME));
+    return;
+  }
+
+  // HTML pages (/, /[nid], etc.) — network-first with cache fallback
+  // This ensures updates propagate but offline still works. The final fallback
+  // is the precached "/", which is the whole point of precaching it: a cold
+  // offline load of a deep route still gets the SPA shell.
+  event.respondWith(
+    fetch(event.request)
+      .then((response) => {
+        if (response.ok) {
+          const clone = response.clone();
+          caches.open(CACHE_NAME).then((cache) => cache.put(event.request, clone));
+        }
+        return response;
+      })
+      .catch(() => caches.match(event.request).then((cached) => cached || caches.match("/")))
+  );
+});

package/package.json

@@ -1,35 +1,93 @@
 {
   "name": "brane",
-  "author": "Ben Newman <bn@cs.stanford.edu>",
-  "version": "0.0.2",
-  "description": "Arbitrary object graph transformation without wasteful full-graph traversals",
+  "version": "0.3.0",
+  "description": "Userspace daemon and CLI for narrative agent sessions",
   "keywords": [
-    "arbitrary",
-    "object",
-    "graph",
-    "traversal",
-    "transformation",
-    "indexing",
-    "abstract",
-    "syntax",
-    "trees",
-    "circular",
-    "cyclic"
+    "agents",
+    "claude",
+    "mcp",
+    "tmux",
+    "daemon",
+    "cli",
+    "llm"
   ],
-  "main": "index.js",
-  "scripts": {
-    "test": "mocha --reporter spec"
+  "homepage": "https://github.com/benjamn/brane#readme",
+  "bugs": {
+    "url": "https://github.com/benjamn/brane/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/benjamn"
   },
-  "homepage": "https://github.com/benjamn/brane",
   "repository": {
     "type": "git",
-    "url": "git://github.com/benjamn/brane.git"
+    "url": "git+https://github.com/benjamn/brane.git"
   },
-  "bugs": {
-    "url": "https://github.com/benjamn/brane/issues"
+  "type": "module",
+  "bin": {
+    "brane": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.d.ts",
+    "!dist/**/*.map",
+    "expo/dist",
+    "protocols",
+    "wiki/shared",
+    "AGENTS.md",
+    "docs",
+    "CONTRIBUTING.md",
+    "CHANGELOG.md",
+    "DESIGN.md",
+    "SECURITY.md",
+    "Dockerfile",
+    "docker-entrypoint.sh"
+  ],
+  "scripts": {
+    "clean": "node scripts/clean-dist.mjs",
+    "prebuild": "npm run clean",
+    "build": "tsc && npm run build:web --prefix expo",
+    "postbuild": "node scripts/chmod-bin.mjs",
+    "prebuild:server": "npm run clean",
+    "build:server": "tsc",
+    "postbuild:server": "node scripts/chmod-bin.mjs",
+    "start": "node dist/cli.js",
+    "test": "tsc && node --test dist/test/*.test.js"
   },
-  "license": "MIT",
   "dependencies": {
-    "mocha": "~2.2.4"
+    "@dagrejs/dagre": "^3.1.1",
+    "better-sqlite3": "^13.0.3",
+    "citty": "^0.1.6",
+    "katex": "^0.18.4",
+    "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-gfm-autolink-literal": "^2.0.1",
+    "mdast-util-gfm-table": "^2.0.0",
+    "mdast-util-gfm-task-list-item": "^2.0.0",
+    "micromark": "^4.0.2",
+    "micromark-extension-gfm-autolink-literal": "^2.1.0",
+    "micromark-extension-gfm-table": "^2.1.1",
+    "micromark-extension-gfm-task-list-item": "^2.1.0",
+    "micromark-extension-math": "^3.1.0",
+    "onnxruntime-node": "^1.21.0",
+    "qrcode-terminal": "^0.12.0",
+    "shiki": "^4.0.2",
+    "sqlite-vec": "^0.1.9",
+    "stream-json": "^3.7.0",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.0.0",
+    "@types/qrcode-terminal": "^0.12.2",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.7.0",
+    "wrangler": "^4.70.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "AGPL-3.0-or-later",
+  "overrides": {
+    "katex": "$katex"
   }
 }

package/protocols/LIVE_loop.md

@@ -0,0 +1,407 @@
+# Protocol: LIVE_loop
+
+The LIVE loop is a cursor-driven long-polling communication protocol for
+brane agents. Every tool named here comes from the **brane** MCP server;
+if another server offers a same-named tool, always use brane's.
+
+Your role in this system is to:
+
+| Phase | Action |
+|-------|--------|
+| **L**isten | Await incoming signals from operator when idle |
+| **I**nterpret | Process recent signals, inferring operator intent and updating context |
+| **V**ocalize | Announce everything you're doing or thinking (non-blocking) |
+| **E**xecute | Take appropriate action after achieving alignment |
+
+## Communication Flow
+
+```mermaid
+flowchart TD
+    L[Listen] --> I[Interpret]
+    I --> V[Vocalize] & E[Execute]
+    V --> E
+    E --> V
+    V --> L
+    style L stroke-width:4px
+```
+
+Listen (bold) is the initial and default state, and the only arrow
+into it comes from Vocalize. Interpret may go straight to Execute when
+what was just listened to clearly grants permission; otherwise it goes
+through Vocalize first. Execute has no path back to Listen except
+through Vocalize: an agent always explains what it executed before it
+goes quiet. Neither has Interpret: a signal, once read, is never left
+unanswered — even "read; nothing changes" is said aloud. (A `listen`
+timeout carries no signal, so it is not a trip through Interpret; it
+is simply Listen again.) The arrows between Vocalize and Execute run
+both ways because that is what narrating *while* acting looks like:
+each step is announced as it begins, and the narration continues while
+the agent works.
+
+The semicolon in "LI;VE" separates the (Listen, Interpret) stage from
+(Vocalize, Execute) output stage.
+
+You must achieve alignment with the operator from listening and interpreting
+before vocalizing or executing any actions. Vocalization is distinct from
+execution because you may vocalize clarifying questions to refine your
+understanding before taking action.
+
+Interpretive alignment should take all recent messages into account. For
+example, if you receive two messages in quick succession — a misspelled
+command and then a correction — interpret them as one coherent instruction.
+
+## Principles
+
+### Narration is your only voice
+
+All communication with the operator should be delivered by your `narrate`
+tool. Do not output text to the terminal, as terminal content is vulnerable
+to compaction. The narrative history is permanent and searchable.
+
+### Read before you speak
+
+`narrate` returns events, but those events are a **receipt, not a poll**.
+They report what had landed by the time your words were already written —
+one beat too late to have shaped them. An agent that uses `narrate` to
+discover signals is perpetually answering the message before last, and
+learns about the correction only after shipping the mistake.
+
+So the order is fixed: **read, interpret, then speak.** Before composing
+anything substantive, do a non-blocking read:
+
+```json
+{ "wait": false, "after": <your cursor> }
+```
+
+It returns immediately and costs one round trip. If it turns up signals,
+interpret them *together with* what you were about to say — they may
+sharpen it, redirect it, or make it moot. This is the
+misspelled-command-then-correction rule above applied to your own speech:
+recent messages must be interpreted as one coherent instruction, and you
+can only do that if you have read all of them first.
+
+### When you find out too late
+
+The race is never fully closed. A signal can land in the gap between your
+read and your write, and `narrate` will hand it back attached to words
+that could not possibly have accounted for it. That is not the failure —
+failing to *notice* is.
+
+When `narrate` returns signals you hadn't seen, say so plainly in your
+next narration and answer them properly. Do not paper over it, and do not
+let the stale narration stand as though it had addressed them. A stale
+narration that is openly corrected costs the operator a few seconds; a
+stale narration presented as a considered answer costs them their trust
+in every other one.
+
+### Narrate often, and listen when idle
+
+Narrating often is still right — it is how the operator sees what you are
+doing, and it is the only voice you have. Read-before-you-speak is not an
+argument for speaking less: a `wait: false` read is nearly free, and it is
+what makes frequent narration *informed* rather than merely frequent. When
+you have nothing to say or do, call `listen` to block and wait for new
+signals.
+
+The one licensed exception is /idle: sent by the operator
+as a signal's first token, it says the work is done and the agent may
+stop listening — report what is unreported, set `summary` to
+`Idle: …`, make one last `wait: false` read, and if it is empty return
+to its prompt with no `listen` parked. Nothing wakes an idle agent but
+the operator.
+
+### Every turn re-reads your whole context
+
+Each tool-call turn you take sends your entire context back through the
+model. Late in a long session that is hundreds of thousands of tokens per
+turn, and it is where nearly all of the cost goes. So narrate as often as
+you like, but don't spend a turn on it by itself:
+
+- **While executing, narrate alongside the work, not before it.** Send the
+  progress narration as a parallel tool call in the same turn as the work
+  it announces: the `Bash`, `Read` or `Edit` it describes. "Running the
+  suite now" belongs in the turn that runs the suite. Only 2% of narrations
+  were batched this way when this was measured, and every other one cost a
+  full re-read (claude-tnlxg5pg:21).
+- **When a narration ends your turn, wait in the same call.** An answer, a
+  question, or a finished report is followed by `listen` anyway, so pass
+  `wait: true` to `narrate`. It posts, then blocks exactly as `listen`
+  would and returns `listen`'s result: one call instead of two. Pass your
+  cursor as `after`, several narratives included, exactly as you would to
+  `listen`. A signal that crossed with your narration comes back at once
+  instead of being slept through. Narrating into another agent's
+  narrative with no `after` waits on both sides: yours, and theirs. If
+  the result carries no `waited_ms` — `wait_ignored` says why when the
+  daemon understood the request (a `before` or `tail` read has nothing to
+  wait for), and a client holding an older tool list drops `wait` without
+  a word — you did not wait: call `listen`. A wait that times out is a
+  `listen` timeout: call `listen` again, don't narrate again. And pass
+  `after`: without it the wait starts from *now*, and a signal that landed
+  before the call but after your last read is skipped.
+
+### Your own words never wake you
+
+Your own narrations, in your narrative or one you narrated into, are
+never an arrival: they don't wake a parked `listen`, end a waiting
+`narrate`, or make a blocking `listen` return at once. So a cursor that
+trails your last narration costs nothing while you wait. They are still
+*returned*: when something else arrives, or on a `wait: false` read,
+you get everything past your cursor, your own words included. That is
+what lets a `listen` after compaction recover what you said, whichever
+cursor you resume from.
+
+### Narration content is stored verbatim
+
+The `say` parameter is stored and rendered exactly as provided. Use
+actual whitespace and formatting — newlines, blank lines, indentation
+— rather than escape sequences. The content is markdown; write it the
+same way you would write any markdown text.
+
+### When a narration does not render as written
+
+Markdown and LaTeX fail quietly here, by design, so `narrate` tells you
+instead: when something in `say` will not render as written, the result
+carries a `warnings` array, each entry with the `fallback` text the
+operator will actually see. Judge from the fallback whether the meaning
+arrived, and apply any fix to your *next* narration rather than
+correcting the last one. `strict: true` refuses to post such a narration
+instead — use it deliberately, never by habit. When a warning comes back,
+read /markdown, whose Warnings section says how to weigh each kind.
+
+### Never ignore operator requests to reenter the LIVE loop
+
+If the operator sends a signal containing "live loop" or similar phrases,
+immediately `narrate` or `listen` to catch up on recent signals. You are
+never too busy to heed the call for redirection.
+
+## Failure modes
+
+The LIVE loop is the execution environment, not optional participation
+in a conversation. Leaving it without being told to is equivalent to
+crashing. These are the ways agents fail at it:
+
+- **Exiting the loop.** Returning to a native prompt instead of calling
+  `listen` again, treating each signal-response cycle as a completed
+  task. The one licensed exit is the operator's /idle; nothing else
+  counts as being told.
+- **Repetitive filler.** An occasional note about resuming the loop is
+  fine. Narrating "In loop" or "Listening" turn after turn when you
+  should be silently blocked on `listen`, and continuing after
+  correction, is not.
+- **Acknowledgment in place of action.** Replying "Understood!" or "On
+  it!" and returning to `listen` without doing the work. Narration is
+  what you say *while* acting, not *instead of* acting.
+- **Silence in place of a report.** The mirror failure: doing the work
+  and dropping straight back to `listen`, so the operator watched it
+  start and never sees it end. Say what happened, and update `summary`,
+  before you go quiet.
+
+## Quick Start
+
+1. Confirm your brane tools are live before anything else — make one
+   real call (e.g. `whoami`) and check that it actually succeeded
+   (see Session Initialization, Step 0). If it errors, the MCP server
+   is still connecting: wait and retry, do not proceed.
+2. Call `read_protocol("LIVE_loop")` if the protocol is not in context
+3. DO NOT under any circumstances begin executing actions before you
+   have explicit direction from the operator, as this skips the L, I,
+   and V steps of the LIVE loop. Do not even speculate about the nature
+   of the task before you actually know, even if the operator has not
+   yet said anything, as this will confuse future readers. Wait.
+
+   **Direction means a signal in your narrative.** The kickoff prompt
+   that starts or revives you does not count — it arrives over tmux and
+   is never an event, so it tells you to enter the loop, not what to
+   work on. Loading context and reading (`listen`, `whoami`,
+   `read_protocol`, opening a file) are always allowed; anything with an
+   effect outside your own session — writes, commands, foreign
+   narration, spawning — waits for the signal. A role protocol that
+   prescribes its own startup procedure (see `keeper.md`) is the one
+   exception: run it, then wait here.
+4. Load context: `listen` with `wait: false` and `tail: 50` for a
+   non-blocking read of recent events
+5. Process any returned signals, then `narrate` with a substantive
+   response (not boilerplate) and set `meta.summary`
+6. If there are no signals yet, keep `listen`ing for them (without
+   `wait: false` this time), and double-check by calling `listen` with
+   `wait: false` again before your next substantive narration (see [Read
+   before you speak](#read-before-you-speak)), as agents often miss a
+   second or third message sent by the operator in their first response,
+   and then must clumsily amend their answers to reflect operator
+   messages they should already have seen
+7. Occasionally, despite your best efforts, a `narrate` will genuinely
+   cross with an operator message, and `narrate` reports the missed
+   message(s). This is fine, but do not make `narrate` your primary
+   mechanism for listening
+
+Both `narrate` and `listen` default to your own narrative.
+
+## Session Initialization
+
+Start every session by catching up on context *before* narrating. Use
+a non-blocking `listen` to load recent history without writing a
+throwaway message:
+
+**Step 0 — Confirm your tools are live:**
+
+When you are spawned or revived, your kickoff prompt can arrive
+*before* the brane MCP server finishes connecting. During that window
+every brane call (`whoami`, `listen`, `narrate`, …) errors. Before you
+do anything else, make one real call — `whoami` is cheapest — and
+inspect the actual result.
+
+- **If the call succeeds**, your tools are live. Proceed to Step 1.
+- **If the call errors or the tool is unavailable**, the MCP server is
+  still connecting. *Do not proceed.* Wait briefly and retry, with a
+  short backoff (e.g. a few seconds, a handful of attempts). Only
+  continue once a brane call genuinely returns.
+
+Make this one call on its own and read its result — do **not** batch
+several optimistic tool calls in a single turn written as if they had
+already succeeded.
+
+**Hard rule — never fabricate around a failure.** A signal, event, or
+fact exists *only* if a real brane response carrying a `seq` delivered
+it. Never narrate, interpret, or take action on top of an errored or
+unobserved tool result, and never invent identifiers (seqs, PR numbers,
+commit hashes) to fill the gap. If calls keep failing after your
+retries, stop and surface that plainly — do not work around it by
+imagining what the results would have been.
+
+**Step 1 — Load context:**
+
+```json
+{
+  "tail": 50,
+  "wait": false
+}
+```
+
+This returns up to 50 recent events immediately. If there are pending
+operator signals, you'll see them here. If the narrative is brand new,
+you'll get just the "Spawned" event (or nothing).
+
+**Step 2 — Narrate with substance:**
+
+After interpreting what you've read, narrate something meaningful —
+a response to pending signals, a summary of your understanding, or
+your intended plan. Set metadata at the same time:
+
+```json
+{
+  "say": "Your substantive response or plan here",
+  "after": <highest seq from step 1>,
+  "meta": {
+    "summary": "What this session is about, then where it stands"
+  }
+}
+```
+
+If there are no pending signals and the narrative is fresh, a brief
+readiness announcement is fine (e.g., "Ready — awaiting signals").
+The point is to avoid narrating filler *before* you've read what's
+pending.
+
+### Pagination
+
+`tail: 50` usually loads enough context to understand the current state;
+`after: 0` loads every event (seq starts at 1, the "Spawned" event). If a
+`tail: 50` read returns 50 events and the first has `seq > 1`, there's
+older history — page backward with `tail: 50, before: <earliest seq>`
+until you reach seq 1. Most sessions never need to page.
+
+## Narrative Metadata
+
+`narrate`'s `meta` parameter persists session metadata the operator sees
+in the narrative list and chat header:
+
+- **`summary`** — what tells this session apart, then where it stands
+
+It's how the operator finds this session in a list of dozens, so name
+what only this session is about — the task or area — before any status,
+even when idle or done. A session with several themes lists them newest
+first: the summary scrolls, but its first words get the attention.
+Reread it at every report and whenever your focus shifts: could the
+operator pick this session out by it?
+
+- Good: "Implementing terminal disconnect overlay" · "Awaiting signals — daemon/server.ts refactor" · "Revive API endpoint: PR #212 merged · earlier: daemon restart race"
+- Bad: "Idle" · "Awaiting signals" · "Working" · "PR #512 merged"
+
+```json
+{ "say": "Starting migration...", "after": 42, "meta": { "summary": "Running database migration" } }
+```
+
+## Context Compaction Recovery
+
+After context compaction:
+
+1. Call `whoami` to rediscover your narrative ID
+2. Call `listen` with `wait: false` and `tail: 50` to reload recent context
+3. Review your narrations to identify which signals you responded to
+4. Narrate a substantive response to any gaps
+
+## MCP Tools
+
+Parameter and response shapes live in the tool schemas your client already
+holds; this table says only what each tool is *for*.
+
+| Tool | Reach for it to |
+|------|-----------------|
+| `narrate` | Vocalize — your only voice. The events it returns are a receipt, not a poll; read before you speak. A `warnings` array rides back when the markdown or LaTeX will not render as written; `strict: true` refuses to post such a narration instead. `wait: true` posts and then listens, in one call. |
+| `listen` | Block until signals arrive — your idle state. Timeouts are normal; call again. With `wait: false`, your read-before-you-speak check. |
+| `whoami` | Get your narrative ID, brane ID, fold, agent type, and role — and any /mentions of you, without settling them. Your first call after a restart. |
+| `revive` | Restart a dead agent session (idempotent). |
+| `narrative_search`, `narrative_info`, `list_branes` | Find and inspect other narratives and branes — see /memory. |
+| `list_protocols`, `read_protocol` | List and read protocol documents. |
+
+`narrate` and `listen` share the cursor parameters `after` / `before` /
+`tail` (the schema explains the per-narrative watermark model) and both
+default to your own narrative.
+
+## Events and Signals
+
+Each event has a `type`:
+
+- `narration` — your own voice
+- `human_signal` — from a human operator: `source` is `web` (the app,
+  on any device) or `local` (this machine's shell)
+- `agent_signal` — from another agent (foreign narration)
+
+`source` (who produced the event) is stamped server-side and cannot be
+spoofed. Other fields — `seq`, `time`, `content`, `re`, `payloads` — appear
+only when relevant.
+
+Sequence numbers are monotonic and never reused, so an `after` cursor never
+misses a signal. When `"self"` is used as a cursor key, the events map
+echoes back a `"<your-nid>": "self"` alias.
+
+## Inter-Agent Communication
+
+Narrate into another agent's narrative by passing its `nid`; your message
+arrives there as an `agent_signal`. To watch for replies from agents you've
+delegated to, pass a multi-narrative cursor — e.g. `{"self": 42,
+"claude-worker1": 15}` — to `narrate` or `listen`.
+
+## Mentions
+
+Writing `@claude-4c7289d1` **addresses** that narrative; the bare
+`claude-4c7289d1` merely **cites** it. A mention gets another agent's
+attention without writing into its log, and never revives it. When a
+`listen`, `narrate` or `whoami` result carries a `mentions` array — or the
+operator tells you to check your mentions — read /mentions. In short: reading
+the source narrative through your cursor is what settles a mention, and an
+unread one keeps coming back.
+
+## Threading
+
+Events take an optional `re` array of back-references: a bare seq (same
+narrative), `"nid:seq"` (cross-narrative), or `"nid"` (whole narrative).
+It's metadata only — `listen` returns all events regardless.
+
+## Related Protocols
+
+- /payloads — receiving, analyzing, and sending file/image payloads
+- /memory — semantic search and cross-narrative context
+- /mentions — addressing other narratives with `@nid`, and settling mentions of you
+- /markdown — where brane renders markdown, what it adds, how readers page, and rendering warnings
+- /idle — the licensed way to stop listening when the work is done