brane 0.1.1 → 0.3.1

package/docs/mentions.md

@@ -0,0 +1,101 @@
+# Mentions
+
+`@claude-4c7289d1` **addresses** a narrative; the bare `claude-4c7289d1`
+**cites** one. Until this existed, the only way to get another agent's
+attention was to narrate into its narrative — which puts a message in someone
+else's conversation, permanently, to say "look over here". A mention is the
+quiet instrument: it leaves the other log untouched and points at what you
+wrote in yours.
+
+That requirement is also the design's whole justification. A mention is
+deliberately **not an event**:
+
+| | ledger row | synthetic event |
+|---|---|---|
+| Writes into the recipient's log | no — *the point* | yes |
+| `nid:seq` permalink space | untouched | diluted (the `tool_uses` argument) |
+| Re-scan / rebuild | idempotent via `UNIQUE` | impossible |
+| Recursion when the copy quotes the handle | can't happen | needs a guard |
+
+The cost is that delivery isn't free: `checkForEvents` returns `null` unless an
+`events` row appeared, so a ledger row alone would wake a parked `listen` that
+finds nothing and parks again — and with `LISTEN_TIMEOUT_BY_AGENT.claude` at
+3400s, "discovered on the next listen" means up to 56 minutes. Mentions
+therefore have their own resolve predicate, threaded through `PendingListen`.
+
+| Piece | Where | Does |
+|---|---|---|
+| `mentionSpec` / `collectMentionSpec` | `src/shared/markdown-mentions.ts` | The one pattern. No bare npm imports, so metro needs no alias |
+| `extractMentions()` | `src/mentions-scan.ts` | The daemon-side walk — the renderer with its output thrown away |
+| `mentions` table | `src/db/schema.ts` | The row, and what became of it |
+| `src/db/mentions.ts` | | record / pending / ack / annotate / dismiss |
+| `recordEventMentions()` | `src/daemon/server.ts` | The scan and the insert |
+| `announceEvent()` | `src/daemon/server.ts` | The one order: record, *then* wake. Every conversational append site calls it |
+| `mentionReceipt()` | `src/daemon/server.ts` | Ack, annotate, report — in that order |
+
+Six things are less obvious than they look:
+
+**One parse, never a second scanner.** Recording runs the *same* mdast walk and
+the *same* spec as the renderer, so a handle fires a notification **iff** the
+operator sees it as a mention. A regex over `content` would be the parallel
+scanner the [Rendering Warnings](rendering-warnings.md) section forbids, and its
+failure is worse here because it is invisible: a pasted log with a handle in a
+fenced block shows as inert code while silently waking an agent. This is also
+why `mdast-util-from-markdown` and `mdast-util-gfm-autolink-literal` are
+`dependencies` — as devDependencies they worked in the checkout and would have
+thrown on first `narrate` from a published tarball.
+
+**Order: mentions, then citations.** Each mdast extension's links are opaque to
+the next, so `narrativeIdLinks` running first consumes the id and strands the
+`@` — which is exactly what brane did before mentions existed. `nidSpec` now
+carries `boundary: before => before !== "@"`, so the two **must ship
+together**: with the veto and without `mentionLinks`, an `@`-prefixed id stops
+rendering as a link at all.
+
+**Two marks, per row, not per narrative.** `sent_at` governs the wake — set on
+delivery, so a mention wakes an agent exactly once. `seen_at` governs the
+reminder — set only by evidence of attention, so a delivered-but-unread mention
+keeps reappearing. They must be separate: if the only thing clearing a mention
+were acknowledgment, an agent that never acked would get a `listen` returning
+instantly forever. And they must be **per row**, because acknowledgment is per
+*source*: a high-water mark over a shared id space settles every lower id when
+one is acked, silently marking read a mention from a narrative the agent never
+opened. `NULL → timestamp` also makes monotonicity structural — there is no
+value that could rewind, which a cursor re-derived from `tail: 50` after a
+restart otherwise can.
+
+**Receiving the event is the acknowledgment.** Interpreting a mention means
+reading its source, and an agent does that by naming the narrative in the
+cursor it already passes. So the evidence and the attention are the same act —
+strictly stronger than an ack tool, which an agent can call reflexively without
+looking. It settles the seqs **actually returned**, never `seq > after`:
+`before` truncates a range and `tail: N` skips the middle, so a bound would
+settle mentions the agent was never shown.
+
+**Settle in the same block as the send.** `mentionReceipt` is spread directly
+into the object handed to `sendToolResult`, so nothing can run between marking
+sent and sending. A resolve that doesn't advance durable state makes the next
+`listen` return instantly, forever, at inference speed, with no operator in the
+loop — the failure that would make the feature worse than not having it.
+`src/test/mentions-listen.test.ts` is the regression guard. The shutdown flush
+is the one deliberate exception: it replies without a receipt, leaving mentions
+unsent rather than marking them delivered to an agent about to lose its bridge.
+
+**Record before you wake, and in one place.** `notifyListenWaiters` resolves a
+parked `listen` **synchronously** — the waiter builds its receipt and acks by
+read inside that call. So an append that wakes before it inserts acks a row
+that does not exist yet: zero rows updated, the mention lands `seen_at NULL`,
+and the agent's cursor has now moved past the one event that could ever settle
+it. It is delivered, read, and permanently unsettled — reappearing in every
+later receipt until someone reads backwards or dismisses it. This is not a
+race; it is deterministic for exactly the agent watching the narrative that
+mentioned it, which is why the feature's own tests missed it: every one of them
+records before any listener parks. `announceEvent()` is therefore the single
+ordering, called from all six sites rather than open-coded at each — the bug
+was six independent chances to get two lines wrong, and a seventh site would
+have had nothing to remind it.
+
+Delivery is at-most-once — `sendToolResult` drops silently on a closing socket
+— so "settled" must never mean "unreachable": `whoami` and
+`listen({mentions: "all"})` replay regardless of either mark. Knobs:
+`mentions.enabled` (kill switch), `mentions.receipt_limit`.

package/docs/multi-brane.md

@@ -0,0 +1,14 @@
+# Multi-Brane
+
+A single daemon can host multiple branes. The **home brane** is auto-generated on first run (`brane-<hex>`). Foreign branes are created by `brane absorb` when importing conversation history from other providers.
+
+- **Narratives** have a `brane_id` column linking them to their brane
+- **Folds** have a `brane_id` column — `brane spawn` inherits the fold's brane_id
+- **Absorb** creates a deterministic foreign brane_id from `sha256(provider:identity_id)`, ensuring re-imports target the same brane
+- **`brane list`** groups narratives by brane with per-brane limits
+- **`GET /api/branes`** returns all branes with narrative counts for the web UI
+- **BraneSwitcher** in the Expo app replaces the old DaemonSwitcher — shows branes in a flat list, filters narratives by selected brane
+
+Brane_id resolution chain for new narratives: fold's `brane_id` → `config default.brane` → home brane (`getBraneId`).
+
+Existing folds are backfilled to the home brane on upgrade (idempotent, runs on every `openDatabase()`).

package/docs/passkeys.md

@@ -0,0 +1,165 @@
+# Passkeys
+
+Passkeys are **designed, spiked and tested on real devices, but not built**.
+This page is the design and the evidence behind it, for whoever builds
+enrollment. The pieces already in the code are per-device tokens (#549,
+#552), the lapse for unused tokens (#555), and the presence check
+(`src/presence.ts`, [Presence Check](presence.md)).
+
+## The rule
+
+**A passkey guards minting a token, never using one.** Every request keeps
+authenticating with its device token, so a browser that cannot do WebAuthn
+— the plain-HTTP fallback, an in-app webview, one with a flaky ceremony —
+keeps working once it holds a token. The ceremony happens only when a new
+device is let in (claude-pbg4whll:21). The worst outcome of a passkey
+failure is a slower way to add a device, never a browser locked out of
+brane.
+
+What else a passkey guards — "Sign out other devices", an agent asking for
+a token — is **not decided** (claude-pbg4whll:40).
+
+## Decisions
+
+| Decision | Why | Where |
+|---|---|---|
+| The RP ID is the daemon's own hostname (`<machine>.<tailnet>.ts.net`) | The daemon works with nothing outside the machine and the tailnet | claude-0d36vrut:16, claude-0d36vrut:21 |
+| The hosted shell (`brane.organelle.dev`) does not share the passkey | It hops to the daemon's own page for the rare ceremony. No `/.well-known/webauthn`, no port 443, no `tailscale serve`, no reliance on related-origins support | claude-pbg4whll:35 |
+| No attestation, random user handle | The daemon learns a public key and nothing about the authenticator — except for the bootstrap key (below) | claude-82b6w9o3:12 |
+| The first enrollment needs the presence check | A software authenticator sets "user verified" with nobody present, and without attestation the daemon cannot tell; an agent acting as this account could otherwise enroll its own passkey | claude-pbg4whll:42 |
+| YubiKeys stay possible and the top tier | Attested hardware proves itself; a key also covers headless Linux | claude-pbg4whll:49, claude-pbg4whll:50 |
+| Ship enrollment before requiring it | Enrolling changes nothing until the restriction is switched on, so it can ship and be lived with first | claude-pbg4whll:33 |
+
+## Evidence
+
+**Spike, headless Chromium** (claude-0d36vrut:21). A virtual authenticator
+against a `node:crypto`-only verifier: single-use challenge, origin
+allowlist, RP ID hash, user-verified flag, ES256 signature. A passkey on
+the daemon's hostname enrolled and signed in on the daemon's page; a
+replayed assertion and an unlisted origin were refused. An RP ID of the
+whole tailnet (`<tailnet>.ts.net`) works on the daemon's page but nothing
+can serve its `.well-known`, so it was dropped.
+
+**Check 1, real devices** (claude-pbg4whll:29). The same verifier on a
+spare port, tailnet-only, with the daemon's Tailscale certificate:
+
+| Browser | Enroll | Sign in | Replay refused |
+|---|---|---|---|
+| iOS Safari | ✅ Face ID | ✅ | ✅ |
+| iOS Chrome | ✅ | ✅ 5/5 after the fix below | not rerun |
+| Mac Chrome 152 | — | ✅ through the phone QR (hybrid) | ✅ |
+| Mac Safari, Firefox, Android, Windows | not tried | | |
+
+- The passkey **synced to iCloud Keychain** (backup-eligible and
+  backed-up flags both set), and Face ID set user-verified.
+- The origin carried the non-standard port (`:47443`) and verified; the
+  port is not part of the RP ID.
+- Mac Chrome did not offer the iCloud passkey directly and went through
+  the phone. Whether a Chrome setting changes that is unverified.
+
+## What the browser side must do
+
+Learned on the phone, then confirmed by the research below:
+
+1. **Have the challenge before the tap.** Fetching it between the tap and
+   `navigator.credentials.get/create` made iOS refuse with
+   `NotAllowedError` (2 of 7 sign-ins succeeded in iOS Chrome before the
+   fix, 5 of 5 after). Fetch the next challenge the moment one is taken.
+2. **One ceremony at a time.** Disable the button and keep a single
+   `AbortController`, aborting the previous request before starting
+   another. A second tap while a prompt was open failed in testing.
+3. **Treat `NotAllowedError` as routine.** It means cancel, timeout, no
+   credential, or no user activation, and since Safari 17.4 WebKit also
+   rate-limits ceremonies (unverified: a vendor blog, no Apple figures).
+   Reset quietly and let the operator tap again; never show it as a fault.
+4. **If no challenge is ready, wait for one** with a spinner, then ask for
+   a fresh tap. Calling the prompt without one is what WebKit refuses.
+
+## Daemon side
+
+- **Challenges** are random, single-use, bound to the pending ceremony, and
+  expire with the ceremony's `timeout` (a few minutes; the exact lifetime is
+  a choice, not a sourced figure).
+- **Verify the full origin, port included**, against the daemon's own list;
+  the RP ID hash; user-verified; the signature.
+- **Ignore `signCount` when it is 0**, which is every synced passkey.
+  Enforce it only for a credential that has reported a non-zero count.
+- **Store at registration:** credential id, public key, algorithm,
+  transports, AAGUID, sign count, and the backup-eligible / backed-up
+  flags. Record which presence method confirmed the enrollment.
+- **When a device-bound key enrolls** (backup-eligible = 0, e.g. a
+  YubiKey), prompt for a second credential as its backup.
+- **Bootstrap attestation:** ask for `attestation: "direct"` on the first
+  enrollment only. A YubiKey 5+ answers with a certificate the daemon can
+  verify against the FIDO Metadata Service by AAGUID; that counts as
+  presence by itself. iCloud passkeys send none and fall back to the
+  presence check.
+
+## Research
+
+From a web survey on making passkeys robust (claude-pbg4whll:70). Claims
+from vendor blogs are marked.
+
+- **`excludeCredentials` on create**, with stored transports; treat
+  `InvalidStateError` ("already registered") as success.
+  [web.dev](https://web.dev/articles/passkey-registration)
+- **`hints: ["security-key", …]`** keeps YubiKeys first-class; without it
+  Chrome on Android may not offer an NFC key. Chrome 128+ honours hints;
+  Safari and Firefox are unverified.
+  [Chrome](https://developer.chrome.com/blog/passkeys-updates-chrome-129)
+- **Discoverable credentials with an empty `allowCredentials`**: a list
+  whose transports are only `internal` makes Chrome hide the phone QR.
+  [Corbado](https://www.corbado.com/blog/webauthn-passkey-qr-code) (vendor)
+- **The Signal API** cleans stale passkeys out of the password manager —
+  the remedy for the orphan the test page left on the operator's phone.
+  `signalAllAcceptedCredentials` after a device is added or removed, never
+  with an empty list (that hides every passkey). Chrome 132+; Safari 26
+  partial; Firefox none.
+  [Chrome](https://developer.chrome.com/docs/identity/webauthn-signal-api)
+- **Feature-detect with `PublicKeyCredential.getClientCapabilities()`**
+  (Safari 17.4+, Chrome 133+, Firefox 135+) to choose which buttons to
+  show, never to block.
+  [web.dev](https://web.dev/articles/webauthn-client-capabilities)
+- **Hybrid (phone QR) is the most fragile path**: Bluetooth on both
+  devices, close together; Chrome on macOS can fail to find the phone after
+  its Bluetooth permission prompt
+  ([Chromium 349393380](https://issues.chromium.org/issues/349393380)).
+- **Passkey autofill (conditional UI) adds little**: brane has no username
+  field and the ceremony is rare.
+- **The RP ID cannot change.** Renaming the machine or the tailnet orphans
+  every passkey; recovery covers it.
+- **WebAuthn refuses a page with a certificate error**, and the HTTP
+  fallback can never run a ceremony.
+
+## Open questions
+
+1. **What a passkey guards beyond adding a device** — the operator's call
+   (claude-pbg4whll:40).
+2. **The flow for approving a new device from one already trusted**: the
+   new device shows a code, the trusted one approves with Face ID. Not
+   designed; includes how the approval returns to an app saved to the home
+   screen, which may open Safari.
+3. **The hop from the hosted shell** to the daemon's page and back must
+   carry a short-lived, single-use approval, never a token.
+4. **Renames**: should the daemon record each passkey's RP ID and warn
+   before a hostname change?
+5. **Untried**: Mac Safari and Firefox; Android; the presence check's
+   Windows/WSL and polkit backends; a YubiKey's attestation and its
+   signature as a presence method (claude-pbg4whll:63).
+
+## Build order
+
+1. ~~Unused-token lapse~~ — #555, verified live: an unscanned meld token
+   was revoked by the sweep 31 s after its deadline (claude-pbg4whll:96).
+2. ~~Devices list~~ — #558: each row records the browser, platform and address
+   it was first presented from, and revoke is a bodiless
+   `POST /api/tokens/:id/revoke` (claude-59qp4ud5:4). See [Token
+   Rotation](token-rotation.md#the-devices-list). Revoking is no more gated
+   than "Sign out other devices" yet; whether a passkey should guard it is
+   open question 1.
+3. **Passkey enrollment and verification**, nothing yet required.
+4. **Wire in `confirmPresence`** for the first enrollment and for
+   recovery, with `reason` built on the daemon.
+5. **Switch the restriction on**: after the first passkey, this machine's
+   account (a tokenless request over `daemon.sock`) can no longer mint
+   device tokens, and meld tickets need a passkey.

package/docs/presence.md

@@ -0,0 +1,202 @@
+# Presence Check
+
+`confirmPresence(reason)` (`src/presence.ts`) asks the operator to prove
+they are at this machine, using the operating system's own
+owner-authentication prompt. It is the piece passkey enrollment and
+recovery rest on, and what [the gate](#the-gate) holds meld, a device's
+sign-out and rotation on. Passing it is what makes someone
+the operator — see [Who the operator is](../SECURITY.md#who-the-operator-is).
+
+## Why passkeys need it
+
+A passkey's "user verified" flag says a person unlocked the authenticator,
+but a software authenticator can set that flag with nobody present (the
+passkey spike did exactly that with a virtual authenticator). iCloud
+passkeys carry no attestation, so the daemon cannot tell one from a
+script. An agent acting as this account could therefore enroll a passkey
+of its own. The first enrollment, and recovery when no passkey works, are
+confirmed here instead: an agent running as the operator can raise the
+system prompt but cannot put a finger on the sensor or type a password it
+does not know.
+
+An attested hardware key (a YubiKey 5 or later) proves itself without this
+check and remains the strongest option; see [Passkeys](passkeys.md).
+
+## Backends
+
+Each runs a tool the OS already ships, so brane carries no native module.
+
+| Platform | Tool | Asks for | Tested |
+|---|---|---|---|
+| macOS | `osascript -l JavaScript` → `LAContext`, policy `deviceOwnerAuthentication` | Touch ID, Apple Watch, or the login password | yes, on a real prompt; and raised by the daemon's gate: approve, decline, cooldown, Ctrl-C (2026-10-05) |
+| Windows, WSL | `powershell.exe` (5.1) → `UserConsentVerifier` | Windows Hello: face, fingerprint, or PIN | no |
+| Linux desktop | `pkcheck` against `dev.brane.confirm-presence` | the user's own password (`auth_self`) | no |
+| Headless Linux | — | `unavailable` | — |
+
+Less obvious than it looks:
+
+- **macOS has no approve button.** The dialog's only ways through are
+  biometrics or the password field, so synthetic clicks can cancel it but
+  never pass it.
+- **Every command is a fixed absolute system path** (`/usr/bin/osascript`,
+  `/usr/bin/pkcheck`, `C:\Windows\System32\…\powershell.exe`), never a
+  bare name on the daemon's inherited `PATH` nor a path built from its
+  environment (`%SystemRoot%`). This is hygiene against a careless agent's
+  `PATH`, not a defence against a hostile one: a process running as the
+  operator can already edit `dist/` or `brane.db`, which brane accepts as
+  out of scope. The check raises the bar for agents that follow the rules.
+- **The reason never enters a script.** On macOS it is an `argv` element;
+  on Windows it is a PowerShell single-quoted literal inside a script sent
+  as `-EncodedCommand` (UTF-16LE base64), which survives WSL interop's
+  quoting untouched.
+- **WSL uses Windows Hello**, not polkit: the prompt appears on the Windows
+  desktop, out of reach of anything inside the Linux VM. PowerShell 7
+  (`pwsh`) lacks the WinRT projection, hence `powershell.exe`.
+- **`canceled` means the operator said no, and nothing else.** A system
+  that took the dialog away, too many wrong attempts, or polkit refusing
+  without asking (a daemon outside the active desktop session, e.g. started
+  over SSH: pkcheck exit 1) are all `failed`.
+- **Linux needs brane's polkit policy installed.** polkit's built-in
+  actions mostly ask for an administrator, which is the wrong question; this
+  one asks the operator to prove they are themselves (`auth_self`), every
+  time (no `_keep`). Without it the check reports `unavailable`; the "no
+  such action" message is matched before the exit code, since pkcheck
+  reports errors as 127 (untested against a real polkit). brane ships no
+  copy of the file; install it with:
+
+  ```sh
+  sudo tee /usr/share/polkit-1/actions/dev.brane.confirm-presence.policy >/dev/null <<'EOF'
+  <?xml version="1.0" encoding="UTF-8"?>
+  <!DOCTYPE policyconfig PUBLIC
+   "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
+   "http://www.freedesktop.org/standards/PolicyKit/1/policyconfig.dtd">
+  <policyconfig>
+    <vendor>brane</vendor>
+    <vendor_url>https://github.com/benjamn/brane</vendor_url>
+    <action id="dev.brane.confirm-presence">
+      <description>Confirm you are at this machine for brane</description>
+      <message>brane wants to confirm you are at this machine before it trusts a new passkey or device</message>
+      <defaults>
+        <allow_any>no</allow_any>
+        <allow_inactive>no</allow_inactive>
+        <allow_active>auth_self</allow_active>
+      </defaults>
+    </action>
+  </policyconfig>
+  EOF
+  ```
+- **Headless Linux is `unavailable` on purpose.** polkit would fall back to
+  a password prompt in the terminal, and agents run in terminals.
+
+## The gate
+
+`PresenceGate` (`src/daemon/presence-gate.ts`) is where the daemon calls
+it, and `src/daemon/gated-routes.ts` holds the routes that ask it. Four
+acts, asked from this machine's shell (a tokenless request over
+`daemon.sock`), wait in the route until the operator answers:
+
+| Act | Route | CLI | The prompt says |
+|---|---|---|---|
+| `meld` | `POST /api/tokens` | `brane meld`, `brane spawn --meld` | add a device to brane |
+| `meld-remote` | `POST /api/tokens/remote` | `brane meld --remote` | add a device to brane on another machine |
+| `revoke-device` | `POST /api/tokens/:id/revoke`, when it signs out a device | `brane token revoke <device>` | sign out a device from brane |
+| `rotate` | `POST /api/token/rotate` | `brane token rotate` | sign out every other device from brane |
+
+A device token is never prompted: the app's Meld sheet, Revoke and "Sign
+out other devices" are the operator's delegate acting, and work from
+anywhere. **An agent's token is refused all three, unasked** (403,
+`presence: "agent"`; `gateStanding`): they are the operator's acts, and an
+agent that follows the rules should never put a dialog in front of the
+operator — one that read exactly like the prompt their own `brane meld`
+raises would be approved out of habit. So an agent cannot `brane spawn
+--meld`; the operator scans from the Meld sheet instead. Who is asking is
+read from the token's kind, never from the address. Revoking an agent is
+not gated, for an agent or the shell; stopping an agent the account
+started is the account's to do.
+
+Less obvious than it looks:
+
+- **The prompt's words are fixed per act.** Nothing from a request reaches
+  them, not a device's label nor its user agent: whoever minted a token
+  chose those, and an agent that could write the prompt could make it read
+  like the one the operator is expecting.
+- **Check, ask, check again.** A request the route would refuse (a bad
+  mint body; revoking this machine's own row, the requester's own, or a row that
+  is not live) is refused before anyone is asked, so the operator never
+  approves something that then fails. The revoke re-checks after the
+  prompt, since rows can change during it.
+- **Rotation asks before `beginRotation`.** A second begin replaces a
+  pending rotation, so a refused request must never reach it: a loop could
+  otherwise void the operator's own rotation without passing a prompt.
+- **One prompt at a time, no queue.** A second gated request while one is
+  up is refused at once (409). After one that was not approved (canceled,
+  timed out, failed, canceled from a device, or withdrawn by its asker) the
+  gate refuses for 15 s (429, with `Retry-After`), so a loop cannot keep a
+  dialog on screen until it is approved out of habit; giving up and asking
+  again is that loop, so a withdrawal counts. Both are global, but only the
+  shell can reach the gate (an agent is refused before it), so only another
+  shell's request can make the operator's `brane meld` wait; the Meld
+  sheet still works regardless. The 409 names the prompt that is up and who asked, since its
+  dialog may read exactly like the one the operator expected.
+- **No dialog outlives its request.** A gated request waits 45 s; if its
+  client goes away first (Ctrl-C), the helper is killed (`runPlan`'s
+  `signal`), which takes the dialog down with it: seen live on macOS
+  (2026-10-05), logged as `aborted`, and followed by the cooldown like any
+  prompt not approved.
+- **Every device hears of it, and can cancel; nothing can approve.** The
+  control socket carries `{ type: "presence", pending }` when a prompt
+  opens (`pending` names the act, the prompt, who asked, and when it
+  expires) and `pending: null` when it closes; a socket that connects
+  mid-prompt is told at once. `POST /api/presence/cancel?id=` closes it,
+  and only a device token may call it: anything on this machine that could
+  cancel could cancel every prompt as it appeared and, with the cooldown,
+  keep `brane token rotate` from ever completing. The asker withdraws by
+  disconnecting. A remote approve would be a device minting a token, which
+  the Meld sheet already does in the open.
+- **Every attempt is a log line**: `[presence] <act> for <who>: approved`,
+  `canceled`, `remote-cancel`, `timeout`, `aborted`, `unavailable`, or
+  refused as busy, cooling down, or `an agent's token` — an agent's attempt
+  raises no prompt but is recorded like one that did.
+- **No prompt, no act.** Where the platform cannot show one (headless
+  Linux, a container), the gated acts are refused with `unavailable`; a
+  device token still does them. The first device of such a machine comes
+  from elsewhere: `brane meld --remote` has the operator's own daemon mint
+  the token, behind this machine's prompt (`meld-remote`), and sends the
+  remote only its hash, which its daemon adopts at startup
+  (`BRANE_DEVICE_TOKEN_SHA256`; see `protocols/fly.md`). The minting daemon
+  keeps nothing: the token is for another daemon, and the response is its
+  only copy. There is no switch that turns the gate off.
+- **Not containment.** `meld-remote` gates the sanctioned way to reach a
+  remote daemon, not the remote: a process that can run `fly secrets set`
+  (or whatever `--send` runs) can hand that daemon a hash of its own
+  making, no brane involved. A device token is never prompted, whoever holds it,
+  so a local process that minted itself one before the gate existed skips
+  it; so does one that restarts the daemon with `--token` or
+  `BRANE_DEVICE_TOKEN_SHA256` set, which adopt a device token at startup. Check the Devices list for devices added by "this machine" or by an
+  agent that you did not add.
+
+## Results
+
+`{ ok: true, method }`, or `{ ok: false, method, reason, detail }` with
+`reason` one of `canceled` (the operator said no), `unavailable` (no prompt
+can be shown here), `failed`, `timeout` (default 120 s), or `aborted` (the
+caller's `signal` withdrew the question, and the helper was killed). It
+never throws.
+
+## Tests
+
+`src/test/presence.test.ts` checks each backend's plan as data — command,
+arguments, quoting, and how each tool's answer is read — so it runs on any
+platform and never raises a prompt. The macOS cancel result it parses was
+recorded from a real dialog.
+
+## For whoever wires it in, or first runs it on Windows
+
+- **Build `reason` on the daemon** from what is being approved, never from
+  text in a request, or an agent writes the prompt's words itself ("Unlock
+  brane"). The prompt naming what it approves is half of what makes it safe.
+- **Windows Hello from a hidden console may open behind other windows**;
+  the desktop API is `RequestVerificationForWindowAsync(hwnd)`. And a
+  timeout that kills `powershell.exe` (or WSL's interop proxy) may leave the
+  dialog open with nobody listening. Both are the first things to watch in
+  a real Windows run.

package/docs/releasing.md

@@ -0,0 +1,104 @@
+# Releasing
+
+Publishing to npm is done by `.github/workflows/release.yml`, and only by it.
+No npm token exists in this repository or its secrets: the job authenticates
+with a short-lived OIDC token ([npm trusted
+publishing](https://docs.npmjs.com/trusted-publishers)). **Agents never run
+`npm publish`**, from a checkout or anywhere else.
+
+`npm publish` is not passed `--provenance`, and needs no flag for it.
+Trusted publishing attests a build by itself when the repository is public
+and leaves attestation out when it is private, where `--provenance` would
+fail the publish on a 422. 0.3.0 was published while the repository was still
+private, so it is the one release with **no provenance attestation**; every
+release since the repository went public carries it, with no workflow
+change.
+
+The trigger is a **published GitHub release**, not a tag push, so the release
+notes and the publish are one act and a stray tag cannot publish anything.
+
+1. Land the version bump on `main` by pull request, with `npm version <v>
+   --no-git-tag-version` so `package-lock.json` moves with it.
+2. Create a GitHub release on `main` tagged `v<version>`, exactly the
+   `package.json` version with a `v` prefix. The workflow refuses any other
+   tag, and refuses a version that is already on the registry.
+3. The **"Set as a pre-release"** checkbox chooses the dist-tag: unchecked
+   publishes under `latest`, checked publishes under `next`. That is the only
+   place the choice is made.
+
+The job builds from scratch (`npm run build` plus the precache check, since
+`dist/` and `expo/dist/` are gitignored and there is no `prepare` script),
+runs the full test suite, prints the `npm pack --dry-run` manifest to the log,
+and then publishes. A failure anywhere before the last step is a red run and
+nothing on the registry.
+
+Trusted publishing needs npm 11.5.1 or newer, which no runner ships, so the job
+runs `npm install -g npm@latest` first. The npm-side configuration lives at
+`https://www.npmjs.com/package/brane/access`, is per package, and is the
+operator's: the trusted publisher entry (`benjamn` / `brane` / `release.yml`,
+no environment), and "Require two-factor authentication and disallow tokens",
+which is what actually retires tokens as a publish path.
+
+A newly created trusted-publisher entry reads **Pending validation** until
+its first successful publish, and npm deletes it if none happens within
+about 48 hours of creation; the access page shows the deadline. So either
+create the entry on the day of the release, or validate a fresh one with a
+release marked pre-release, which publishes to `next` and leaves `latest`
+where it was.
+
+`src/cli.ts` reads its version from `package.json` at startup, so
+`brane --version` reports whatever was published rather than a string that
+has to be bumped by hand.
+
+## The app ships with the release
+
+The shared app (the `brane` worker in `worker/wrangler.toml`, at
+`app_domain`'s default host) serves the web app of the version npm calls
+`latest`, and nothing else. A merge to `main` deploys nothing: `ci.yml` only
+tests.
+
+- After an ordinary release publishes, `release.yml`'s `deploy-app` job runs
+  `.github/workflows/deploy-app.yml` with the release's version. A pre-release
+  deploys nothing.
+- `deploy-app.yml` does not build. It waits until the registry has the version
+  and names it `latest` (right after a publish either can lag by up to a
+  minute), unpacks `npm pack <name>@<version>`, checks the tarball's name,
+  version and `expo/dist/index.html`, runs the precache check, and
+  `wrangler deploy`s that `expo/dist`. The shared app is therefore the same
+  bytes every daemon of that version installs and serves itself, by
+  construction rather than by a second build that is supposed to match.
+- It is its own job because a publish cannot be undone and a deploy can be
+  repeated: a Cloudflare failure is a re-run of that job, never a second
+  release.
+- **Redeploy or roll back** by dispatching `deploy-app.yml` from the Actions
+  tab with a version. It refuses a version that is not `latest`, so a rollback
+  is `npm dist-tag add brane@<version> latest` (the operator's, like everything
+  on the registry) and then the dispatch. The dispatch checks out the branch it
+  is run from, so an old version's bundle is deployed with *that branch's*
+  `wrangler.toml` and precache check, not its tag's: the route is where the
+  app lives whatever its version. A version that isn't `latest` is refused
+  only after the registry-lag retries, about four minutes in.
+- **A `wrangler.toml` change is first exercised by the next release's
+  deploy.** A merge deploys nothing and `wrangler deploy --dry-run` doesn't
+  talk to Cloudflare, so watch that release's `deploy-app` job. Declaring the
+  custom domain needs zone permissions on `CLOUDFLARE_API_TOKEN`, not only
+  Workers ones; if the job fails there, the fix is the token and a re-run, and
+  the publish before it stands.
+
+**Staging is Isolate.** A daemon running `main` (after `/rrr`) serves its own
+bundle, built from that checkout, so Isolate on it shows everything merged
+since the last release, together, before a release promotes it to the shared
+app. Every daemon serves its own version's app the same way, which is also
+what an older install has: `brane meld --local`, or Isolate, gives it the app
+it shipped with. Between releases, then, a daemon running `main` is newer than
+the shared app, the ordinary case of an older app on a newer daemon.
+
+The deploy names no host and no package: the package name comes from
+`package.json`, and the route is declared in `worker/wrangler.toml` as a
+custom domain, with `workers_dev = false` so it is the only place the shared
+app is served and the Cloudflare dashboard holds nothing the repository
+doesn't. That route is `CONFIG_DEFAULTS.app_domain`, the host `brane meld`
+points at, and `src/test/wrangler-route.test.ts` keeps the two equal. A fork
+that publishes under its own name and serves its own app changes `name` in
+`package.json`, `name` and the route in `wrangler.toml`, and
+`CONFIG_DEFAULTS.app_domain`.

package/docs/rendering-warnings.md

@@ -0,0 +1,22 @@
+# Rendering Warnings
+
+Every renderer here fails quietly, on purpose. Unparseable LaTeX comes back as its own source rather than KaTeX's red error markup; a `$…$` run that trips the currency guard is escaped into prose; an unclosed fence swallows the rest of the message. That is right for the **reader**, who wants a document and not a diagnostic — and exactly wrong for the **writer**, who otherwise never learns the equation did not set.
+
+`narrate` closes that gap without reopening it for the reader: rendering is unchanged, and the reasoning the renderers were already doing is reported back instead of discarded. `diagnoseMarkdown()` runs on `say`, and the result grows a `warnings` array **only when non-empty** — a narration that renders as written gets the byte-identical receipt it always did.
+
+| kind | fires on | what the operator sees instead |
+|---|---|---|
+| `math_parse_error` | KaTeX refused the LaTeX | the literal source with its delimiters |
+| `math_demoted` | a `$…$` run the guard rejected, whose content is TeX-ish (`\cmd`, `^{`, `_{`) | the source verbatim, dollars and all |
+| `math_unclosed` | `\(` or `\[` with no partner, or a `$$` that opens a line and never closes | literal text — or, for `$$`, everything after it as one math block. A mid-sentence `$$` or a `$$$` is literal and stays quiet |
+| `fence_unclosed` | a code fence that never closes | everything after it as one code block |
+
+Two properties make the warnings worth acting on:
+
+**It is the real parse, not a lookalike.** The runs come from the same `prepareMathMarkdown` and the same micromark pass the export uses — `mathHtmlExtension(onError)` and `prepareMathMarkdown(md, onIssue)` grew optional collectors rather than gaining a second scanner beside them. So a warning fires *iff* the operator's view differs from intent. A parallel scanner would eventually disagree with the renderer, and a linter that cries wolf is worse than none.
+
+**Every warning carries its `fallback`** — the literal text that will appear. Whether a failure *matters* is a judgment only the author can make and it turns almost entirely on that text: `$E = mc^2$` shown as source still communicates, a `pmatrix` shown as source is line noise. `protocols/markdown.md` tells agents to make exactly that call. `fence_unclosed` is the one that is never benign.
+
+**Advisory by default, refusing only on request.** A warning never blocks a narration. The protocol tells agents to apply the fix *forward* — write the next one better — rather than to correct the last one, because a live loop that pauses to re-render a blemish has traded the thing narration is for.
+
+`strict: true` is the opt-in exception, shaped after `wait: false` on `listen`: the narration is refused rather than posted, the call comes back as a tool error carrying the same diagnostics, and **nothing is written** — which is why `diagnoseMarkdown` runs before the summary update and before payloads are copied into managed storage. A refusal that had already copied files would leave orphans, and the golden rule forbids cleaning them up. Agents are told to reach for it deliberately (a derivation, a table the message builds on), never by habit: every refusal is a round trip the operator waits through.