brane 0.3.1 → 0.3.3

package/dist/shared/view-url.js

@@ -91,10 +91,72 @@ export function parseLineSpec(s) {
     const end = m[2] ? Number(m[2]) : undefined;
     return end !== undefined && end >= line ? { line, lineEnd: end } : { line };
 }
+/** Which melded daemon a same-origin link means, named by its home `brane_id`
+ *  (the registry's dedup key, and no secret), in the link's **fragment**:
+ *  `#daemon=brane-f66d2b`.
+ *
+ *  A tab's active daemon lives in its own `sessionStorage`, and a link opened in
+ *  a new tab (⌘-click, middle-click, `target="_blank"`) starts with none: it
+ *  falls back to this browser's *default* daemon, which on a shared app with
+ *  several melded need not be the one the link was written from. So in-app
+ *  hrefs carry this param, and an arriving tab whose slot is still empty
+ *  adopts it as its active daemon before anything connects (`expo/lib/api.ts`,
+ *  `adoptDaemonByBraneId`). A tab that already has one ignores it, which is
+ *  what keeps a reload from undoing a later switch. Plain clicks navigate
+ *  within the tab and never put it in the URL.
+ *
+ *  It says which daemon, not what you are looking at, so it rides where the
+ *  connection does (`connectionFragment`): a fragment reaches no server, and
+ *  the shared host's edge, a daemon's request log and a link unfurler never
+ *  see it. It is not `brane`, because a daemon hosts several branes and the
+ *  list already filters by one; this names the daemon. A brane_id this browser
+ *  has not melded is ignored, and the default applies as before. */
+export const DAEMON_PARAM = "daemon";
 /** The params that describe *which daemon*, as opposed to what you are looking
  *  at. They are origin-scoped: meaningful to the page that received them, never
- *  to be carried onward. */
-export const CONNECTION_PARAMS = ["host", "token"];
+ *  to be carried onward. `daemon` is one of them: cleaned on arrival like the
+ *  token, and dropped by Isolate and Meld, whose token already says. */
+export const CONNECTION_PARAMS = ["host", "token", DAEMON_PARAM];
+/** An in-app href (path, optional query, optional fragment) with `daemon` set
+ *  to `braneId` in its fragment, replacing any already there and leaving the
+ *  query, which is the view, untouched. Without a `braneId` the href comes
+ *  back unchanged, so a caller that does not know its daemon yet still gets a
+ *  working link. */
+export function withDaemonFragment(href, braneId) {
+    if (!braneId)
+        return href;
+    const hashAt = href.indexOf("#");
+    const beforeHash = hashAt === -1 ? href : href.slice(0, hashAt);
+    const params = new URLSearchParams(hashAt === -1 ? "" : href.slice(hashAt + 1));
+    params.set(DAEMON_PARAM, braneId);
+    return `${beforeHash}#${params.toString()}`;
+}
+/** The `daemon` param from a location hash (with or without its `#`), or null
+ *  when absent or empty. */
+export function daemonFromHash(hash) {
+    return new URLSearchParams(hash.startsWith("#") ? hash.slice(1) : hash).get(DAEMON_PARAM) || null;
+}
+/** The brane_id an in-app link should name: the tab's active entry's, falling
+ *  back to the first entry when `activeId` is missing or stale, which is what
+ *  the root layout connects to in that case. Null with nothing melded. */
+export function activeDaemonBraneId(daemons, activeId) {
+    return (daemons.find((d) => d.id === activeId) ?? daemons[0])?.brane_id ?? null;
+}
+/** Which registry entry a page arriving with `#daemon=<braneId>` should make
+ *  this tab's active one, or null to leave things as they are.
+ *
+ *  Only an **empty** slot is filled (`tabActiveId` is the tab's own
+ *  sessionStorage value, not the cross-tab default it falls back to). A new
+ *  tab has none; a reloaded, restored or duplicated tab has one and keeps it.
+ *  That matters because the router puts the initial fragment back on its
+ *  first URL write, so `#daemon=` can outlive a daemon switched later in the
+ *  same tab, and a reload must not switch it back. A brane_id this browser
+ *  has not melded is no instruction at all. */
+export function daemonToAdopt(daemons, tabActiveId, braneId) {
+    if (tabActiveId !== null)
+        return null;
+    return daemons.find((d) => d.brane_id === braneId)?.id ?? null;
+}
 /** A search string with the connection params removed and everything else left
  *  alone, ready to hand to `history.replaceState`.
  *

package/dist/test/archive-gate.test.js

@@ -0,0 +1,22 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { archiveRefusal } from "../daemon/archive-gate.js";
+const ended = { status: "ended", mcpConnected: false, tmuxLive: false };
+describe("archiveRefusal", () => {
+    it("allows an ended narrative with nothing running", () => {
+        assert.equal(archiveRefusal(ended), null);
+    });
+    it("refuses a narrative whose status is not ended", () => {
+        assert.ok(archiveRefusal({ ...ended, status: "active" }));
+        assert.ok(archiveRefusal({ ...ended, status: null }));
+    });
+    it("refuses an ended row with an agent still on the bridge", () => {
+        // The stale row the menu also treats as running: hiding it would hide a
+        // live agent.
+        assert.match(archiveRefusal({ ...ended, mcpConnected: true }) ?? "", /connected/);
+    });
+    it("refuses an ended row whose tmux session is still up", () => {
+        assert.match(archiveRefusal({ ...ended, tmuxLive: true }) ?? "", /running/);
+    });
+});
+//# sourceMappingURL=archive-gate.test.js.map

package/dist/test/markdown-math.test.js

@@ -1,7 +1,7 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { micromark } from "micromark";
-import { math } from "micromark-extension-math";
+import { math } from "../math-syntax.js";
 import { MATH_BLOCK_CSS, prepareMathMarkdown, isMathContent, renderMathHtml } from "../shared/markdown-math.js";
 import { mathHtmlExtension, katexStyleFor } from "../math.js";
 import { readFileSync } from "node:fs";

package/dist/test/membrane-quips.test.js

@@ -0,0 +1,62 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { QuipLoop, shuffled } from "../shared/membrane-quips.js";
+// The caption's order: one shuffle per page load, then a fixed loop through
+// it — every line once before any line twice, the same order each time round.
+const list = ["a", "b", "c", "d", "e"];
+/** A seeded generator, so a "random" shuffle is the same on every run. */
+function seeded(seed) {
+    return () => {
+        seed = (seed * 1103515245 + 12345) % 2 ** 31;
+        return seed / 2 ** 31;
+    };
+}
+describe("shuffled", () => {
+    it("is a permutation, and leaves its input alone", () => {
+        const before = [...list];
+        const out = shuffled(list, seeded(7));
+        assert.deepEqual([...out].sort(), before);
+        assert.deepEqual(list, before);
+    });
+    it("can produce every order", () => {
+        const seen = new Set();
+        for (let s = 1; s < 2000; s++)
+            seen.add(shuffled(list.slice(0, 3), seeded(s)).join(""));
+        assert.equal(seen.size, 6);
+    });
+    it("clamps a rand that returns 1", () => {
+        assert.equal(shuffled(list, () => 1).length, list.length);
+    });
+});
+describe("QuipLoop", () => {
+    it("shows every line once per cycle, and the same cycle each time round", () => {
+        const loop = new QuipLoop(list, seeded(3));
+        const first = [loop.current()];
+        for (let i = 1; i < list.length; i++)
+            first.push(loop.next());
+        assert.equal(new Set(first).size, list.length);
+        const second = [loop.next()];
+        for (let i = 1; i < list.length; i++)
+            second.push(loop.next());
+        assert.deepEqual(second, first);
+    });
+    it("never shows the same line twice in a row", () => {
+        const loop = new QuipLoop(list, seeded(11));
+        let prev = loop.current();
+        for (let i = 0; i < list.length * 3; i++) {
+            const q = loop.next();
+            assert.notEqual(q, prev);
+            prev = q;
+        }
+    });
+    it("does not move until told to", () => {
+        const loop = new QuipLoop(list, seeded(5));
+        assert.equal(loop.current(), loop.current());
+    });
+    it("holds a single line", () => {
+        const one = ["solo"];
+        const loop = new QuipLoop(one);
+        assert.equal(loop.next(), one[0]);
+    });
+});
+//# sourceMappingURL=membrane-quips.test.js.map

package/dist/test/mo-glyph.test.js

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { MO_GLYPH_BOX, MO_GLYPH_PATH } from "../shared/mo-glyph.js";
+import { MO_GLYPH_BOX, MO_GLYPH_MARGIN, MO_GLYPH_PATH } from "../shared/mo-glyph.js";
 test("mo-glyph: closed subpaths, absolute commands only, every point inside the box", () => {
     assert.match(MO_GLYPH_PATH, /^M/);
     assert.match(MO_GLYPH_PATH, /Z$/);
@@ -18,5 +18,7 @@ test("mo-glyph: closed subpaths, absolute commands only, every point inside the
     const mid = MO_GLYPH_BOX / 2;
     assert.ok(Math.abs(Math.min(...xs) + Math.max(...xs) - 2 * mid) < 2);
     assert.ok(Math.abs(Math.min(...ys) + Math.max(...ys) - 2 * mid) < 2);
+    // The caption under the glyph is spaced by this (MembraneEmpty.web.tsx).
+    assert.ok(Math.abs(Math.min(...ys) - MO_GLYPH_MARGIN) < 0.01, `ink top is ${Math.min(...ys)}`);
 });
 //# sourceMappingURL=mo-glyph.test.js.map

package/dist/test/narrative-menu.test.js

@@ -69,7 +69,6 @@ describe("narrativeMenuItems", () => {
             "Recolor",
             "Twin",
             "End",
-            "Archive",
         ]);
     });
     it("swaps End for Revive once the session is over", () => {
@@ -93,8 +92,23 @@ describe("narrativeMenuItems", () => {
         assert.ok(labels({ role: "absorbed", status: "ended" }).includes("Revive"));
     });
     it("flips the archive item both ways", () => {
-        assert.ok(labels({ archived: false }).includes("Archive"));
-        assert.ok(labels({ archived: true }).includes("Unarchive"));
+        assert.ok(labels({ status: "ended", archived: false }).includes("Archive"));
+        assert.ok(labels({ status: "ended", archived: true }).includes("Unarchive"));
+    });
+    it("offers Archive only once the session has ended", () => {
+        const running = labels({ status: "active", mcpConnected: true });
+        assert.ok(!running.includes("Archive") && !running.includes("Unarchive"));
+        // The same stale-row test as Revive: an ended row with an agent still on
+        // the bridge is running, and isn't archivable yet.
+        assert.ok(!labels({ status: "ended", mcpConnected: true }).includes("Archive"));
+        assert.ok(labels({ status: "ended" }).includes("Archive"));
+    });
+    it("always offers Unarchive on an archived narrative", () => {
+        for (const status of ["active", "ended", null]) {
+            for (const mcpConnected of [true, false]) {
+                assert.ok(labels({ archived: true, status, mcpConnected }).includes("Unarchive"), `status: ${status}, mcpConnected: ${mcpConnected}`);
+            }
+        }
     });
     it("flips isolate by where the app is served from", () => {
         assert.ok(labels({ isIsolated: false }).includes("Isolate"));

package/dist/test/view-url.test.js

@@ -1,6 +1,6 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { CANONICAL_TABS, isIsolated, parseActiveTab, parsePinnedTabs, serializePinned, viewParams, parseLineSpec, buildIsolateUrl, buildMeldUrl, terminalOnlyHref, withoutConnectionHash, withoutConnectionParams, connectionFragment, } from "../shared/view-url.js";
+import { CANONICAL_TABS, isIsolated, parseActiveTab, parsePinnedTabs, serializePinned, viewParams, parseLineSpec, buildIsolateUrl, buildMeldUrl, terminalOnlyHref, withoutConnectionHash, withoutConnectionParams, connectionFragment, withDaemonFragment, daemonFromHash, activeDaemonBraneId, daemonToAdopt, } from "../shared/view-url.js";
 // These pin the URL contract that the Isolate menu item depends on. It opens
 // the same narrative on the *other* origin — a shared app, or a daemon's own
 // bundle — and the tab layout and open file live in sessionStorage, which is
@@ -219,6 +219,9 @@ describe("withoutConnectionHash", () => {
             ["#other=1&token=t", "#other=1"],
             ["host=h:1&token=t", ""],
             ["#token=a&token=b&x=1", "#x=1"],
+            // `daemon` names which daemon too, so it is consumed like the token.
+            ["#daemon=brane-f66d2b", ""],
+            ["#host=h:1&daemon=brane-f66d2b&token=t&x=1", "#x=1"],
         ];
         for (const [input, expected] of cases) {
             assert.equal(withoutConnectionHash(input), expected, JSON.stringify(input));
@@ -624,4 +627,106 @@ describe("terminalOnlyHref", () => {
         assert.equal(parsePinnedTabs(url.searchParams.get("pinned") ?? undefined).size, 0);
     });
 });
+describe("withDaemonFragment", () => {
+    // A link opened in a new tab arrives with no active daemon in that tab's
+    // sessionStorage; the fragment is how it finds the one the link was written
+    // from. So the question each case asks: is the daemon named, in the
+    // fragment, and is the view the href's query already described left exactly
+    // as it was?
+    const BRANE = "brane-f66d2b";
+    it("names the daemon in the fragment of a bare path", () => {
+        assert.equal(withDaemonFragment("/", BRANE), `/#daemon=${BRANE}`);
+        assert.equal(withDaemonFragment(`/${NID}`, BRANE), `/${NID}#daemon=${BRANE}`);
+    });
+    it("leaves the query, the view, exactly as it was", () => {
+        const href = `/${NID}?tab=files&path=src%2Fa.ts&line=10-20`;
+        const url = new URL(withDaemonFragment(href, BRANE), "https://example.test");
+        assert.equal(url.pathname + url.search, href);
+        assert.equal(url.searchParams.get("daemon"), null);
+        assert.equal(daemonFromHash(url.hash), BRANE);
+    });
+    it("replaces a daemon already there, and keeps any other fragment param", () => {
+        const url = new URL(withDaemonFragment(`/${NID}?scrollToSeq=4#x=1&daemon=old`, BRANE), "https://example.test");
+        const frag = new URLSearchParams(url.hash.slice(1));
+        assert.deepEqual(frag.getAll("daemon"), [BRANE]);
+        assert.equal(frag.get("x"), "1");
+        assert.equal(url.searchParams.get("scrollToSeq"), "4");
+    });
+    it("returns the href unchanged when the daemon is not known", () => {
+        for (const none of [null, undefined, ""]) {
+            assert.equal(withDaemonFragment(`/${NID}?scrollToSeq=4`, none), `/${NID}?scrollToSeq=4`);
+        }
+    });
+    it("reads back through daemonFromHash, and is what the fragment cleaner removes", () => {
+        const url = new URL(withDaemonFragment(`/${NID}?scrollToSeq=4`, BRANE), "https://example.test");
+        assert.equal(daemonFromHash(url.hash), BRANE);
+        assert.equal(daemonFromHash(url.hash.slice(1)), BRANE);
+        assert.equal(withoutConnectionHash(url.hash), "");
+        assert.equal(withoutConnectionParams(url.search), "?scrollToSeq=4");
+    });
+    it("is absent from daemonFromHash when missing or empty", () => {
+        assert.equal(daemonFromHash(""), null);
+        assert.equal(daemonFromHash("#"), null);
+        assert.equal(daemonFromHash("#daemon="), null);
+        assert.equal(daemonFromHash("#token=t"), null);
+    });
+    it("is not carried by Isolate or Meld, whose token already names the daemon", () => {
+        // Isolate and Meld seed from the page's search string; a stray `daemon`
+        // there (an old link) must not ride along in either half of the URL.
+        const opts = {
+            host: SHARED_SPA_HOST,
+            protocol: "https:",
+            search: `?scrollToSeq=4&daemon=${BRANE}`,
+            path: `/${NID}`,
+            conn: CONN,
+            view: viewParams("chat", new Set()),
+        };
+        for (const built of [buildIsolateUrl(opts), buildMeldUrl(opts)]) {
+            const { params, conn } = open(built);
+            assert.equal(params.get("daemon"), null, built);
+            assert.equal(conn.get("daemon"), null, built);
+            assert.equal(params.get("scrollToSeq"), "4", built);
+            assert.equal(conn.get("token"), CONN.token, built);
+        }
+    });
+});
+describe("the daemon a tab names, and the one it adopts", () => {
+    // The registry entries these read, as `expo/lib/registry.ts` stores them:
+    // `id` is the display key the tab's slot holds, `brane_id` what a link names.
+    const CHALK = { id: "ben@chalk", brane_id: "brane-aaaaaa" };
+    const SLATE = { id: "ben@slate", brane_id: "brane-bbbbbb" };
+    const BOTH = [CHALK, SLATE];
+    it("a link names the tab's active daemon", () => {
+        assert.equal(activeDaemonBraneId(BOTH, SLATE.id), SLATE.brane_id);
+        assert.equal(activeDaemonBraneId(BOTH, CHALK.id), CHALK.brane_id);
+    });
+    it("falls back to the first entry when the active id is missing or stale, as the layout connects", () => {
+        assert.equal(activeDaemonBraneId(BOTH, null), CHALK.brane_id);
+        assert.equal(activeDaemonBraneId(BOTH, "ben@gone"), CHALK.brane_id);
+    });
+    it("names nothing with nothing melded, so the link stays bare", () => {
+        assert.equal(activeDaemonBraneId([], null), null);
+        assert.equal(withDaemonFragment("/", activeDaemonBraneId([], null)), "/");
+    });
+    it("a new tab, whose slot is empty, adopts the daemon its link named", () => {
+        assert.equal(daemonToAdopt(BOTH, null, SLATE.brane_id), SLATE.id);
+    });
+    it("a tab that already has a daemon keeps it, so a reload never undoes a switch", () => {
+        // The router restores the initial fragment on its first URL write, so a
+        // tab opened on SLATE and later switched to CHALK can still say SLATE.
+        assert.equal(daemonToAdopt(BOTH, CHALK.id, SLATE.brane_id), null);
+        assert.equal(daemonToAdopt(BOTH, SLATE.id, SLATE.brane_id), null);
+    });
+    it("a daemon this browser has not melded is no instruction at all", () => {
+        assert.equal(daemonToAdopt(BOTH, null, "brane-cccccc"), null);
+        assert.equal(daemonToAdopt([], null, SLATE.brane_id), null);
+    });
+    it("round-trips: what one tab names, a fresh tab adopts", () => {
+        for (const from of BOTH) {
+            const href = withDaemonFragment(`/${NID}`, activeDaemonBraneId(BOTH, from.id));
+            const named = daemonFromHash(new URL(href, "https://example.test").hash);
+            assert.equal(daemonToAdopt(BOTH, null, named), from.id);
+        }
+    });
+});
 //# sourceMappingURL=view-url.test.js.map

package/docs/daemon-api.md

@@ -27,7 +27,7 @@ until someone lists it. An agent also may not revive or prompt a
 | `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 |
+| `PATCH` | `/api/narratives/:id/archive` | Archive/unarchive a narrative; archiving a running one is a 409 (`src/daemon/archive-gate.ts`) |
 | `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) |

package/docs/math.md

@@ -7,6 +7,7 @@ LaTeX in narrative markdown renders through **KaTeX**, in the app and in the HTM
 | `renderMathHtml()` | `src/shared/markdown-math.ts` | The one KaTeX call. `htmlAndMathml`; unparseable LaTeX falls back to the literal source, not KaTeX's red error markup |
 | `prepareMathMarkdown()` | `src/shared/markdown-math.ts` | Pre-parse normalization, run by both sides before micromark/mdast |
 | `mathHtmlExtension()`, `katexStyleFor()` | `src/math.ts` | Export only: micromark hookup, and the inlined stylesheet |
+| `math()` | `src/math-syntax.ts` | Server only: the `$` syntax extension, vendored from `micromark-extension-math` (see below) |
 | `public/katex/` | `expo/` | The app's stylesheet + woff2, vendored by `npm run sync:katex` |
 | `diagnoseMarkdown()` | `src/markdown-diagnostics.ts` | The same pipeline run to *report* rather than render — see [Rendering Warnings](rendering-warnings.md) |
 
@@ -29,4 +30,6 @@ Two more things are less obvious than they look:
 
 **Fonts don't come along by themselves.** KaTeX lays its span tree out entirely in CSS and needs its woff2 faces; without them math is a pile of overlapping glyphs. The export inlines only the families the document reaches for (~166 KB of base64 for an equation-dense narrative, nothing at all for one with no math), derived from the stylesheet so a KaTeX upgrade can't silently drop a face. The app can't inline per document, so it serves `public/katex/` — vendored the way `pdf.min.mjs` already is, because metro bundles a CSS *import* but never copies the `url(fonts/…)` it points at. The `<link>` lives in **`public/index.html`**, which is the real HTML template; `app/+html.tsx` is kept in step but is not what ships.
 
+**The server vendors the syntax half of `micromark-extension-math`.** That package's index loads its own `mathHtml()` too, and with it `katex` at the range it pins (`^0.16.0`). Root `overrides` dedupe that onto our katex in a checkout, but npm ignores a dependency's `overrides`, so every `npm install brane` got a second, older katex — never called, since `src/math.ts` is our `mathHtml`, but loaded, and flagged by `npm audit`. `src/math-syntax.ts` is upstream 3.1.0's tokenizers with TypeScript annotations and nothing else changed (80,000 fuzzed parses matched upstream event for event); the package is no longer a root dependency. The app still imports the package: it ships prebuilt, built under `expo/`'s own overrides. If upstream ever changes how it tokenizes, the two parsers can drift, so carry the change into `src/math-syntax.ts` by hand.
+
 `src/shared/markdown-math.ts` is also the first shared module to import an npm package. Metro resolves a module's dependencies from its own directory and `src/shared` sits outside the expo project root, so `metro.config.js` maps `katex` explicitly — the next shared module with a bare import will need the same.

package/docs/mcp.md

@@ -66,4 +66,4 @@ Core tools available via MCP:
 
 Narratives have persistent `summary` and `title` columns. Agents set them via the `meta` parameter on `narrate`. The daemon broadcasts metadata changes over the control WebSocket as `type: "meta"` messages. The Expo app renders the summary as a subtitle below the narrative ID.
 
-Narratives can be **archived** via `PATCH /api/narratives/:id/archive`. Archived narratives are hidden from the default list but preserved in the database.
+Narratives can be **archived** via `PATCH /api/narratives/:id/archive`. Archived narratives are hidden from the default list but preserved in the database. Only a narrative whose session is over can be archived: the daemon answers 409 while its status isn't `ended`, an agent is on its bridge, or its tmux session is up (`src/daemon/archive-gate.ts`), so archiving can't hide a running agent. Unarchiving is never refused.

package/docs/releasing.md

@@ -9,10 +9,12 @@ publishing](https://docs.npmjs.com/trusted-publishers)). **Agents never run
 `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.
+fail the publish on a 422. 0.3.0 and 0.3.1 were published while the
+repository was still private, so they carry **no provenance attestation**;
+every release after the repository goes public will, with no workflow
+change. Check `gh repo view --json visibility` before a release's notes
+say which it is: the 0.3.1 CHANGELOG entry in its tarball claims
+provenance it does not have.
 
 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.

package/docs/token-rotation.md

@@ -208,8 +208,10 @@ Cline's per-session files) meant no harness's plumbing had to change.
   nothing. A connected external client (no tmux session) is not adopted,
   and lands on a fresh `external-*` narrative once, at the upgrade.
   Adopted agent rows don't trigger the plaintext-token warning.
-- **Archiving revokes** a narrative's agent token when its session is not
-  running. Unarchiving brings nothing back; a revive mints a new one.
+- **Archiving revokes** a narrative's agent token. Only an ended narrative
+  can be archived (the daemon answers 409 otherwise; see
+  `src/daemon/archive-gate.ts`), so there is never a live session to cut
+  off. Unarchiving brings nothing back; a revive mints a new one.
 - **An external goes with its dialer, always.** An external's token
   records the token that dialed it (`minted_by`); it is that token's
   credential in another form, since one `/ws/mcp` dial mints it, so

package/docs/view-urls.md

@@ -56,8 +56,19 @@ pins, Files path and line, the `?scrollToSeq=` selection) goes through
 since the stack did not grow. So the URL keeps that state and Back returns to
 it, but it never costs an extra Back: browsing ten files is one entry, not ten.
 A bare link to the narrative you are in, with no seq, goes nowhere. The list
-is a jump too: **All narratives** in the switcher pushes it, so Back returns
-to the narrative, whether or not a list was already beneath. The header has no
+is a jump too: a swipe down on the narrative's header card dismisses it to
+a pushed list, so Back returns to the narrative, whether or not a list was
+already beneath. **All narratives** in the switcher, in a browser, does not
+navigate this tab at all: it is a link that opens the list in a new one, on
+the same daemon (see "A new tab names its daemon" below). On native, and in
+the web app launched from the home screen, it pushes like the swipe: there is
+no tab to open, and on iOS a `_blank` link from a home-screen app lands in a
+browser view that shares none of its storage, so it would open on the meld
+screen. So does
+**Archive** in the narrative's 🦠 menu, once the daemon has confirmed it (the
+pushed list fetches on mount, and nothing is broadcast to correct a fetch that
+raced the archive); Back returns to the archived narrative. Archiving from the
+list's own menu just drops the row and goes nowhere. The header has no
 ← of its own; Back is the browser's.
 
 Back is instant and complete because the Stack keeps the screens behind the
@@ -132,3 +143,30 @@ come back across an in-app card tap and two tab changes. So the module-level
 consume is what gets the credentials into storage early, `clearMeldUrl` is
 what actually clears the address bar, and `clearStoredConnection` still ends
 the flow.
+
+**A new tab names its daemon.** Which melded daemon a tab is on lives in that
+tab's `sessionStorage` (`expo/lib/registry.ts`), and a tab opened from a link
+starts with none: ⌘-click, middle-click, long-press "Open in New Tab" and
+`target="_blank"` are all `noopener`, which gets no copy. It falls back to
+this browser's *default* daemon, which on a shared app with several melded
+need not be the one the link came from. So every in-app anchor names it:
+`inAppLinkProps` (the `@nid`, `nid:seq` and file links in prose, the narrate
+rows in tool groups) and `newTabLinkProps` (**All narratives**) render their
+href with `#daemon=<home brane_id>` (`DAEMON_PARAM`, `withDaemonFragment`),
+while a plain click still navigates in place by the clean path. It goes in the
+fragment because it says which daemon, not what you are looking at: it is a
+connection param (`CONNECTION_PARAMS`), and like the token it never reaches the
+shared host's edge, a daemon's request log or a link unfurler. On arrival,
+`consumeConnectionFromLocation` in `expo/lib/api.ts` hands it to
+`adoptDaemonByBraneId` at module evaluation, before the root layout reads the
+registry, and cleans it off with the token. The rules are pure functions
+beside the param (`activeDaemonBraneId`, `daemonToAdopt`), tested in
+`src/test/view-url.test.ts`; `registry.ts` only reads and writes storage for
+them. Adoption fills only an **empty** slot. The router restores the initial fragment on its first URL write (see
+above), so the param can sit in the address bar after a daemon
+switched later in that tab, and a reload must not switch back; a tab that has
+a daemon, reloaded, restored or duplicated, keeps it. A brane_id this browser
+has not melded is ignored, and the default applies. It is `daemon`, not
+`brane`, because one daemon hosts several branes and the list already filters
+by one. It names a daemon and carries no credential, so it is safe to copy.
+Isolate and Meld never carry it: their token already picks the daemon.

package/docs/web-app.md

@@ -13,7 +13,7 @@ The Expo app runs as a web PWA served by the daemon (and optionally via Cloudfla
 - **Quick bar** — macros (via MacroMenu component) + quick keys
 - **Full software keyboard** — multitouch with sticky/held modifiers
 - **Live updates** — control WebSocket pushes `status`, `meta`, and `new_events` hints
-- **Archive/unarchive** — swipe or long-press to archive narratives
+- **Archive/unarchive** — from the 🦠 menu, on a list card's status badge or in the narrative's header. Archive is offered only once the session has ended (the same test that swaps End for Revive); Unarchive on any archived narrative. Archiving from the header goes to the list as a jump, so Back returns — see [View URLs](view-urls.md)
 - **Payload rendering** — inline display of image payloads in chat
 - **Export** — download a narrative as standalone HTML via `/api/narratives/:id/export?format=html`. Foreign rows carry their speaker's hue inline, from the same `speakerColor` / `speakerBgColor` the chat uses, at the 🎨 Recolor salt the device sends as `&palette=` — the one place the salt leaves the browser. With messages selected, the menu offers both sides of the selection — **those messages only**, or the conversation with **those messages left out** — see [Export Scope](export-scope.md)
 - **Brane switcher** — dropdown to filter narratives by brane, add/switch daemons. Each brane row (and "All branes") shows its running metered cost as `$2441.72 (138) + 100.2 AIC (1)` — one total per unit with the number of sessions it covers, so a per-session figure can be read off without the line asserting one; the list screen re-reads `/api/branes` (debounced) when a cost `meta` arrives, since the total includes archived narratives the screen never loads. **Devices** lists every token on the active daemon (this device, this machine's CLI and agents, each melded device by browser, platform, address and when it was last seen, and any meld QR not yet scanned) with a Revoke on each other device; **Sign out other devices**, at the foot of that list, rotates instead — see [Token Rotation](token-rotation.md#the-devices-list)