brane 0.3.0 → 0.3.2

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

@@ -1,14 +1,24 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { CANONICAL_TABS, SHARED_SPA_HOST, isIsolatedHost, 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, } 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 — the shared SPA at brane.organelle.dev
-// or a daemon's own bundle — and the tab layout and open file live in
-// sessionStorage, which is origin-scoped. So the query string is the only thing
-// that crosses, and every assertion below is really asking the same question:
-// does the view you were looking at survive the hop?
+// 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
+// origin-scoped. So the query string is the only thing that crosses, and every
+// assertion below is really asking the same question: does the view you were
+// looking at survive the hop?
+//
+// The app carries no host of its own: "isolated" is `location.host` equal to
+// the connection's host, and the way out of a daemon's bundle is whatever the
+// daemon reports as its app host. So the shared host here is deliberately not
+// brane's; any host serving the bundle is a shared app.
 const CONN = { host: "chalk.tail1234.ts.net", token: "tok-abc123" };
 const NID = "claude-0b9okmy2";
+/** The page's host while on a shared app. */
+const SHARED_SPA_HOST = "shell.example.test";
+/** What the daemon reports as its `app_domain`: where a daemon's own bundle
+ *  hops out to, which need not be the shared app the operator came from. */
+const APP_HOST = "app.example.test";
 /** Every subset of the tab set, as a Set — 8 of them. */
 function pinPowerset() {
     const out = [];
@@ -146,13 +156,19 @@ describe("parseActiveTab / parsePinnedTabs", () => {
         }
     });
 });
-describe("isIsolatedHost", () => {
-    it("treats only the shared SPA as un-isolated", () => {
-        assert.equal(isIsolatedHost(SHARED_SPA_HOST), false);
-        for (const host of ["chalk.tail1234.ts.net", "localhost", "127.0.0.1", "brane.example.com"]) {
-            assert.equal(isIsolatedHost(host), true, host);
+describe("isIsolated", () => {
+    it("is true only when the page is served by the daemon it is connected to", () => {
+        assert.equal(isIsolated(CONN.host, CONN.host), true);
+        assert.equal(isIsolated("CHALK.tail1234.TS.NET", CONN.host), true, "hosts are case-insensitive");
+        for (const host of [SHARED_SPA_HOST, "brane.organelle.dev", "main.brane.organelle.dev", "localhost:8081", "127.0.0.1:8081"]) {
+            assert.equal(isIsolated(host, CONN.host), false, host);
         }
     });
+    it("counts the port: a daemon's bundle is reached on its port", () => {
+        assert.equal(isIsolated("192.168.1.20:7777", "192.168.1.20:7777"), true);
+        assert.equal(isIsolated("192.168.1.20:7777", "192.168.1.20:8888"), false);
+        assert.equal(isIsolated("192.168.1.20", "192.168.1.20:7777"), false);
+    });
 });
 /** Parse a built URL back into something assertable. */
 /** A built URL, taken apart the way the app takes it apart: `params` is the
@@ -234,7 +250,8 @@ describe("connectionFragment", () => {
         for (const c of CASES) {
             const view = params(c);
             const url = new URL(buildIsolateUrl({
-                hostname: CONN.host,
+                host: CONN.host,
+                appHost: APP_HOST,
                 protocol: "https:",
                 search: "?scrollToSeq=42",
                 path: `/${NID}`,
@@ -258,14 +275,17 @@ describe("connectionFragment", () => {
 describe("buildIsolateUrl", () => {
     it("targets the shared SPA when leaving a daemon, and melds it back", () => {
         const { origin, pathname, params, conn } = open(buildIsolateUrl({
-            hostname: CONN.host,
+            host: CONN.host,
+            appHost: APP_HOST,
             protocol: "https:",
             search: "?token=old-token",
             path: `/${NID}`,
             conn: CONN,
             view: viewParams("files", new Set(["terminal"]), "src/cli.ts", 4, 9),
         }));
-        assert.equal(origin, `https://${SHARED_SPA_HOST}`);
+        // Out of a daemon's bundle, the target is what the daemon reported, not
+        // any host the app knows.
+        assert.equal(origin, `https://${APP_HOST}`);
         assert.equal(pathname, `/${NID}`);
         // The connection rides in the fragment, never the query string: a query
         // string is sent to the SPA's host, a fragment is not.
@@ -280,7 +300,7 @@ describe("buildIsolateUrl", () => {
     });
     it("targets the daemon's own bundle when leaving the SPA, with no host param", () => {
         const { origin, pathname, params, conn } = open(buildIsolateUrl({
-            hostname: SHARED_SPA_HOST,
+            host: SHARED_SPA_HOST,
             protocol: "https:",
             search: `?host=${CONN.host}&token=${CONN.token}`,
             path: `/${NID}`,
@@ -299,7 +319,7 @@ describe("buildIsolateUrl", () => {
     it("follows the page's scheme to the daemon, so plain http stays http", () => {
         for (const [protocol, scheme] of [["https:", "https"], ["http:", "http"]]) {
             const { origin } = open(buildIsolateUrl({
-                hostname: SHARED_SPA_HOST,
+                host: SHARED_SPA_HOST,
                 protocol,
                 search: "",
                 path: `/${NID}`,
@@ -308,39 +328,59 @@ describe("buildIsolateUrl", () => {
             }));
             assert.equal(origin, `${scheme}://${CONN.host}`, protocol);
         }
-        // The shared SPA is https-only, whatever the page you left was served over.
+        // The hosted shell is https-only, whatever the daemon's bundle you left
+        // was served over (a LAN session is plain http).
         const { origin } = open(buildIsolateUrl({
-            hostname: "localhost",
+            host: "192.168.1.20:7777",
             protocol: "http:",
             search: "",
             path: `/${NID}`,
-            conn: CONN,
+            conn: { host: "192.168.1.20:7777", token: CONN.token },
+            appHost: APP_HOST,
             view: viewParams("chat", new Set()),
         }));
-        assert.equal(origin, `https://${SHARED_SPA_HOST}`);
+        assert.equal(origin, `https://${APP_HOST}`);
+    });
+    it("has nowhere to go from a daemon's bundle that reported no app host, and says so", () => {
+        // A daemon from before `app_domain` rode in /api/status, or one the
+        // status probe could not reach: the menu hides Isolate rather than
+        // handing out a link to a host the app made up.
+        for (const appHost of [undefined, null, ""]) {
+            assert.equal(buildIsolateUrl({ host: CONN.host, protocol: "https:", search: "", path: `/${NID}`, conn: CONN, appHost, view: {} }), null, String(appHost));
+        }
+        // From a shared app the way *in* needs no app host at all.
+        assert.ok(buildIsolateUrl({ host: SHARED_SPA_HOST, protocol: "https:", search: "", path: `/${NID}`, conn: CONN, view: {} }));
+    });
+    it("treats any host serving the bundle as a shared app, and hops in to the daemon from it", () => {
+        for (const host of ["brane.organelle.dev", "main.brane.organelle.dev", "fork.example", "localhost:8081"]) {
+            const { origin, conn } = open(buildIsolateUrl({ host, protocol: "https:", search: "", path: `/${NID}`, conn: CONN, view: {} }));
+            assert.equal(origin, `https://${CONN.host}`, host);
+            assert.equal(conn.get("host"), null, host);
+        }
     });
     it("never carries the departing origin's credentials", () => {
         // A stale host/token in the search string is the danger case: the SPA's
         // meld params must not follow you onto the daemon's own origin, where the
         // host is wrong and the URL would carry a second copy of the token.
-        for (const hostname of [SHARED_SPA_HOST, CONN.host]) {
+        for (const host of [SHARED_SPA_HOST, CONN.host]) {
             const { params, conn } = open(buildIsolateUrl({
-                hostname,
+                host,
+                appHost: APP_HOST,
                 protocol: "https:",
                 search: "?host=stale.example.com&token=stale-token&tab=files",
                 path: `/${NID}`,
                 conn: CONN,
                 view: viewParams("files", new Set()),
             }));
-            assert.deepEqual(params.getAll("host"), [], hostname);
-            assert.deepEqual(params.getAll("token"), [], hostname);
-            assert.notEqual(conn.get("host"), "stale.example.com", hostname);
-            assert.deepEqual(conn.getAll("token"), [CONN.token], hostname);
+            assert.deepEqual(params.getAll("host"), [], host);
+            assert.deepEqual(params.getAll("token"), [], host);
+            assert.notEqual(conn.get("host"), "stale.example.com", host);
+            assert.deepEqual(conn.getAll("token"), [CONN.token], host);
         }
     });
     it("keeps params it doesn't model, like the scroll target", () => {
         const { params } = open(buildIsolateUrl({
-            hostname: SHARED_SPA_HOST,
+            host: SHARED_SPA_HOST,
             protocol: "https:",
             search: "?scrollToSeq=42&scrollTo=1787255699631&theme=dark",
             path: `/${NID}`,
@@ -355,7 +395,7 @@ describe("buildIsolateUrl", () => {
         // This is why the URL alone isn't enough: what's in the address bar can be
         // older than what you're looking at.
         const { params } = open(buildIsolateUrl({
-            hostname: SHARED_SPA_HOST,
+            host: SHARED_SPA_HOST,
             protocol: "https:",
             search: "?tab=chat&pinned=chat&path=old/file.ts&line=1",
             path: `/${NID}`,
@@ -369,7 +409,7 @@ describe("buildIsolateUrl", () => {
     });
     it("lets live state at its default clear a stale param", () => {
         const { params } = open(buildIsolateUrl({
-            hostname: SHARED_SPA_HOST,
+            host: SHARED_SPA_HOST,
             protocol: "https:",
             search: "?tab=files&pinned=terminal&path=old/file.ts&line=1-9",
             path: `/${NID}`,
@@ -384,7 +424,7 @@ describe("buildIsolateUrl", () => {
         // The restore path deliberately skips router.setParams, so this is the
         // case the whole overlay exists for: an empty search string, a full view.
         const { params } = open(buildIsolateUrl({
-            hostname: SHARED_SPA_HOST,
+            host: SHARED_SPA_HOST,
             protocol: "https:",
             search: "",
             path: `/${NID}`,
@@ -398,15 +438,15 @@ describe("buildIsolateUrl", () => {
     });
     it("accepts a search string with or without its leading ?", () => {
         const view = viewParams("files", new Set(), "a.ts");
-        const withQ = open(buildIsolateUrl({ hostname: SHARED_SPA_HOST, protocol: "https:", search: "?scrollToSeq=7", path: `/${NID}`, conn: CONN, view }));
-        const without = open(buildIsolateUrl({ hostname: SHARED_SPA_HOST, protocol: "https:", search: "scrollToSeq=7", path: `/${NID}`, conn: CONN, view }));
+        const withQ = open(buildIsolateUrl({ host: SHARED_SPA_HOST, protocol: "https:", search: "?scrollToSeq=7", path: `/${NID}`, conn: CONN, view }));
+        const without = open(buildIsolateUrl({ host: SHARED_SPA_HOST, protocol: "https:", search: "scrollToSeq=7", path: `/${NID}`, conn: CONN, view }));
         assert.equal(withQ.params.get("scrollToSeq"), "7");
         assert.deepEqual([...withQ.params], [...without.params]);
     });
     it("encodes paths that would otherwise break the URL", () => {
         for (const path of ["docs/a file with spaces.md", "src/c#sharp.ts", "a/b/c/d.ts", "notes/100% done.md", "x?y=z.ts", "π/unicode.ts"]) {
             const url = buildIsolateUrl({
-                hostname: SHARED_SPA_HOST,
+                host: SHARED_SPA_HOST,
                 protocol: "https:",
                 search: "",
                 path: `/${NID}`,
@@ -419,9 +459,9 @@ describe("buildIsolateUrl", () => {
     it("preserves every view in the grid, in both directions", () => {
         for (const c of CASES) {
             const view = params(c);
-            for (const hostname of [SHARED_SPA_HOST, CONN.host]) {
+            for (const host of [SHARED_SPA_HOST, CONN.host]) {
                 const { params: got, conn } = open(buildIsolateUrl({
-                    hostname, protocol: "https:", search: "", path: `/${NID}`, conn: CONN, view,
+                    host, appHost: APP_HOST, protocol: "https:", search: "", path: `/${NID}`, conn: CONN, view,
                 }));
                 assert.equal(got.get("tab"), view.tab ?? null, label(c));
                 assert.equal(got.get("pinned"), view.pinned ?? null, label(c));
@@ -439,7 +479,7 @@ describe("buildIsolateUrl", () => {
         for (const c of CASES) {
             const view = params(c);
             const out = new URL(buildIsolateUrl({
-                hostname: SHARED_SPA_HOST,
+                host: SHARED_SPA_HOST,
                 protocol: "https:",
                 search: "?scrollToSeq=42",
                 path: `/${NID}`,
@@ -447,8 +487,10 @@ describe("buildIsolateUrl", () => {
                 view,
             }));
             const back = new URL(buildIsolateUrl({
-                hostname: out.hostname,
+                host: out.host,
                 protocol: out.protocol,
+                // The daemon's bundle is told where out is, as /api/status would.
+                appHost: APP_HOST,
                 search: out.search,
                 path: `/${NID}`,
                 conn: CONN,
@@ -456,7 +498,9 @@ describe("buildIsolateUrl", () => {
                 // the screen does when it mounts.
                 view: viewParams(parseActiveTab(out.searchParams.get("tab") ?? undefined), parsePinnedTabs(out.searchParams.get("pinned") ?? undefined), out.searchParams.get("path") ?? undefined, parseLineSpec(out.searchParams.get("line")).line, parseLineSpec(out.searchParams.get("line")).lineEnd),
             }));
-            assert.equal(back.origin, `https://${SHARED_SPA_HOST}`, label(c));
+            // Back out lands where the daemon says, which is the page we left only
+            // if its app_domain names it; here it names APP_HOST.
+            assert.equal(back.origin, `https://${APP_HOST}`, label(c));
             assert.equal(back.pathname, `/${NID}`, label(c));
             assert.equal(back.searchParams.get("scrollToSeq"), "42", label(c));
             const conn = new URLSearchParams(back.hash.slice(1));
@@ -477,7 +521,7 @@ describe("buildMeldUrl", () => {
     // has never heard of that daemon.
     it("stays on the shared SPA when that's where you are", () => {
         const url = new URL(buildMeldUrl({
-            hostname: SHARED_SPA_HOST,
+            host: SHARED_SPA_HOST,
             protocol: "https:",
             search: "",
             path: `/${NID}`,
@@ -500,7 +544,8 @@ describe("buildMeldUrl", () => {
     });
     it("stays on the daemon's own bundle when that's where you are", () => {
         const url = new URL(buildMeldUrl({
-            hostname: CONN.host,
+            host: CONN.host,
+            appHost: APP_HOST,
             protocol: "https:",
             search: "",
             path: `/${NID}`,
@@ -516,9 +561,10 @@ describe("buildMeldUrl", () => {
     });
     it("goes the opposite way from Isolate, from either origin", () => {
         // The whole difference between the two menu items, stated once.
-        for (const hostname of [SHARED_SPA_HOST, CONN.host]) {
+        for (const host of [SHARED_SPA_HOST, CONN.host]) {
             const opts = {
-                hostname,
+                host,
+                appHost: APP_HOST,
                 protocol: "https:",
                 search: "",
                 path: `/${NID}`,
@@ -527,16 +573,16 @@ describe("buildMeldUrl", () => {
             };
             const meld = new URL(buildMeldUrl(opts));
             const isolate = new URL(buildIsolateUrl(opts));
-            assert.equal(meld.hostname, hostname, `meld stays put from ${hostname}`);
-            assert.notEqual(isolate.hostname, hostname, `isolate flips from ${hostname}`);
+            assert.equal(meld.host, host, `meld stays put from ${host}`);
+            assert.notEqual(isolate.host, host, `isolate flips from ${host}`);
         }
     });
     it("carries the same view Isolate would, over the whole grid", () => {
         for (const c of CASES) {
             const view = params(c);
-            for (const hostname of [SHARED_SPA_HOST, CONN.host]) {
+            for (const host of [SHARED_SPA_HOST, CONN.host]) {
                 const url = new URL(buildMeldUrl({
-                    hostname, protocol: "https:", search: "?scrollToSeq=42", path: `/${NID}`, conn: CONN, view,
+                    host, appHost: APP_HOST, protocol: "https:", search: "?scrollToSeq=42", path: `/${NID}`, conn: CONN, view,
                 }));
                 assert.equal(url.searchParams.get("scrollToSeq"), "42", label(c));
                 assert.equal(new URLSearchParams(url.hash.slice(1)).get("token"), CONN.token, label(c));
@@ -550,7 +596,7 @@ describe("buildMeldUrl", () => {
     it("hands out an http link when the page itself is http", () => {
         // A LAN session without TLS must not emit https links the phone can't load.
         const url = new URL(buildMeldUrl({
-            hostname: "192.168.1.20:7777",
+            host: "192.168.1.20:7777",
             protocol: "http:",
             search: "",
             path: `/${NID}`,

package/dist/test/wrangler-route.test.js

@@ -0,0 +1,27 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_DEFAULTS } from "../commands/config.js";
+// The shared app's host is written in two places: the route the worker is
+// deployed to (worker/wrangler.toml) and the default `app_domain` that
+// `brane meld` points a QR at and a daemon's bundle hops out to. A fork that
+// changes one and not the other melds phones to a host that serves nothing,
+// so they are pinned together here.
+//
+// This reads *source*, which the npm tarball does not carry, so it skips when
+// the source is absent rather than failing `brane doctor` on every install.
+const root = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const WRANGLER = join(root, "worker", "wrangler.toml");
+describe("the worker's route", () => {
+    it("is CONFIG_DEFAULTS.app_domain, as a custom domain, with no workers.dev alias", (t) => {
+        if (!existsSync(WRANGLER))
+            return t.skip("source is not present (an installed package)");
+        const toml = readFileSync(WRANGLER, "utf8").replace(/#.*$/gm, "");
+        const routes = [...toml.matchAll(/\{\s*pattern\s*=\s*"([^"]+)"\s*,\s*custom_domain\s*=\s*true\s*\}/g)].map((m) => m[1]);
+        assert.deepEqual(routes, [CONFIG_DEFAULTS.app_domain]);
+        assert.match(toml, /^workers_dev\s*=\s*false\s*$/m);
+    });
+});
+//# sourceMappingURL=wrangler-route.test.js.map

package/dist/tmux.js

@@ -171,6 +171,17 @@ function download(url, dest, redirects = 0) {
 export function tmuxQuote(word) {
     return `'${word.replace(/'/g, `'\\''`)}'`;
 }
+/** A request's `terminal_size`, if it is a usable grid: the size the
+ *  requesting viewer's pane last measured, which a new session should start
+ *  at. Anything else — absent, non-integer, out of range — is null, and the
+ *  caller falls back to the last size applied to any session. */
+export function parseTerminalSize(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const { cols, rows } = value;
+    const ok = (n) => Number.isInteger(n) && n >= 1 && n <= 10000;
+    return ok(cols) && ok(rows) ? { cols, rows } : null;
+}
 /** The `new-session` line `newTmuxSession` sends, as tmux will parse it. */
 export function newSessionLine(opts) {
     const parts = ["new-session", "-d", "-s", tmuxQuote(opts.name), "-c", tmuxQuote(opts.cwd)];

package/docker-entrypoint.sh

@@ -109,8 +109,18 @@ fi
 # Clear stale daemon meta from the persisted volume — PIDs from a previous
 # container life are never valid in a new container, but may collide with
 # a live PID here (e.g., tailscaled) and trip the "already running" check.
+#
+# Not the ports, though. Every melded device's URL and every fold's hook
+# config names them, so the daemon comes back on the ones it had, as it
+# does after any restart; clearing them moved both on every boot. The main
+# port's row still goes (the fold registration below waits for the daemon
+# to write it back), so it is read first and handed back with --port. The
+# HTTP fallback port's row stays: the daemon only ever takes it as a hint
+# for what to bind, and nothing reads it while daemon_tls is unset.
+PREV_PORT=$(gosu brane sqlite3 /home/brane/.brane/brane.db \
+    "SELECT value FROM meta WHERE key = 'daemon_port';" 2>/dev/null || true)
 gosu brane sqlite3 /home/brane/.brane/brane.db \
-    "DELETE FROM meta WHERE key IN ('daemon_pid','daemon_token','daemon_port','daemon_version','daemon_tls','daemon_http_port','daemon_socket');" \
+    "DELETE FROM meta WHERE key IN ('daemon_pid','daemon_token','daemon_port','daemon_version','daemon_tls','daemon_socket');" \
     2>/dev/null || true
 
 # Register the default workspace as a fold (idempotent) once the daemon is up.
@@ -138,4 +148,7 @@ gosu brane sqlite3 /home/brane/.brane/brane.db \
 # with EADDRNOTAVAIL. Binding broadly is safe here — Fly's only reachable
 # networks are Tailscale and the private 6PN, both of which the userspace
 # IP filter already restricts.
-exec gosu brane brane daemon start --foreground --bind 0.0.0.0 "$@"
+# --port: the port the last boot had (above). If something else holds it
+# now, the daemon exits before writing its row back, so the next boot finds
+# none and lets the OS pick.
+exec gosu brane brane daemon start --foreground --bind 0.0.0.0 ${PREV_PORT:+--port "$PREV_PORT"} "$@"

package/docs/daemon-api.md

@@ -24,10 +24,10 @@ until someone lists it. An agent also may not revive or prompt a
 
 | Method | Path | Purpose |
 |--------|------|---------|
-| `GET` | `/api/status` | Daemon status (brane_id, hostname, username, pid, port, uptime_ms, `tls: { state, expires_at, ... }`) |
+| `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) |
@@ -36,9 +36,9 @@ until someone lists it. An agent also may not revive or prompt a
 | `GET` | `/api/folds?archived=1` | List registered fold directories (includes brane_id; archived hidden unless asked) |
 | `POST` | `/api/folds` | Register a fold (`{ path, brane_id? }`) — idempotent; see [Folds API](#folds-api) for who may register what |
 | `PATCH` | `/api/folds/archive` | Soft-hide/unhide a fold (`{ path, archived }`) — never deletes the row |
-| `POST` | `/api/spawn` | Spawn agent (`{ agent, fold_path, role?, model?, re?, extra_args? }`) — used by both the web app and `brane spawn` |
+| `POST` | `/api/spawn` | Spawn agent (`{ agent, fold_path, role?, model?, re?, extra_args?, terminal_size? }`) — used by both the web app and `brane spawn` |
 | `GET` | `/api/spawn-history` | Recent distinct `launch_args`, most-recent first (spawn dialog quick-fill) |
-| `POST` | `/api/run` | Run non-agent command (`{ command, fold_path }`) |
+| `POST` | `/api/run` | Run non-agent command (`{ command, fold_path, terminal_size? }`) |
 | `GET` | `/api/run-history` | Commands utility sessions have run before (by basename), most-recent first — the spawn dialog's Utility list; derived from `narratives`, nothing stored |
 | `POST` | `/api/revive/:nid` | Revive a dead agent session (`{ prompt?, no_prompt?, agent? }`) — see [Revive API](#revive-api) |
 | `POST` | `/api/search` | Semantic search over narrative history (`{ query, limit?, brane_ids? }`) |
@@ -85,7 +85,7 @@ Control WebSocket commands (client → server):
 
 ## Spawn API
 
-`POST /api/spawn` accepts `{ agent, fold_path, role?, model?, re?, extra_args? }` and returns the new narrative object with `mcp_connected` status. The fold picker modal lets the operator choose which registered fold to spawn into.
+`POST /api/spawn` accepts `{ agent, fold_path, role?, model?, re?, extra_args?, terminal_size? }` and returns the new narrative object with `mcp_connected` status. `terminal_size` (`{ cols, rows }`) is the grid the requesting viewer's terminal pane last measured; the session starts at it rather than at the last size applied to any session, so its first screen is not redrawn through a resize — see [Launch residue in scrollback](terminal-mirroring.md#launch-residue-in-scrollback). `/api/run` takes it too. The fold picker modal lets the operator choose which registered fold to spawn into. The dialog's Agent list is the built-in adapters plus an "Other…" entry that takes any agent name, as `brane spawn <agent>` does: the daemon accepts any `[A-Za-z0-9_-]+` name it can find with `which`, and an agent without an adapter gets tmux, MCP config and mirroring but no session resumption. What is typed there splits like the args box, so the first word is the agent and the rest lead its `extra_args`.
 
 This is the **only** spawn path. The web UI calls it, and so does `brane spawn` — the CLI resolves a daemon (starting one if needed), POSTs here with `fold_path` set from `cwd` and `-- <args>` as `extra_args`, and then does only terminal-shaped work with the response: `--meld`'s QR code and `--attach`. It does not open the database or create tmux sessions itself, so tmux bootstrap (`ensureTmux`), terminal sizing, and MCP config writing happen once, daemon-side, identically for both callers. Two consequences follow from that and are intended: the agent binary is resolved against the *daemon's* `PATH`, and MCP config files point at the checkout the *daemon* runs from — not the CLI you invoked.
 

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

@@ -6,15 +6,15 @@ 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.
 
-Published versions carry **no provenance attestation**, and `npm publish` is
-not passed `--provenance`. npm will only attest a build from a public
-repository, and this one stays private until brane is announced: its history
-is a place to experiment, with invited collaborators or without, and it goes
-public before any public promotion. With the flag, the publish step would fail
-on a 422 every time. Without it, trusted publishing leaves attestation out for
-a private repository and turns it on by itself for a public one, so the first
-release after the repo goes public carries provenance with no workflow
-change.
+`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 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.
@@ -51,3 +51,56 @@ 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/terminal-mirroring.md

@@ -209,3 +209,35 @@ left a hairline between lit rows. Each row starts on a fractional pixel, and
 each layer anti-aliased its own edge onto the shared boundary pixel. A
 full-cell gradient with hard stops (linear for bars, conic for quadrants)
 has the span's own edges, and the browser snaps those to whole pixels.
+
+## Launch residue in scrollback
+
+The mirror shows the pane's whole scrollback (`capture-pane -S -`), so
+anything a TUI drew and abandoned before the session settled is on screen for
+good. The case that prompted this section: a new fold opened under a stack of
+yellow `────` rules and three copies of "Accessing workspace". It was Claude
+Code's folder-trust dialog, redrawn at each width the window passed through:
+first created at `lastTerminalSize` (the last size applied to *any* session),
+then fitted to the viewer. Every stale frame went up into history, reflowed,
+its full-width rules now wider than the pane. The live screen was clean; the
+input box was pushed off the bottom only because the history above it was
+tall and wide.
+
+Two things address it, and neither touches the live screen:
+
+- **Start at the viewer's size.** The app remembers the grid its terminal pane
+  last measured (`lastTerminalSize()`, `expo/lib/terminal.ts`) and sends it as
+  `terminal_size` on `POST /api/spawn` and `POST /api/run`. The daemon starts
+  the tmux session at that grid when it is usable (`parseTerminalSize`,
+  `src/tmux.ts`, pinned by `src/test/terminal-size.test.ts`) and falls back to
+  `lastTerminalSize` otherwise, which is still what `brane spawn` from a shell
+  gets. A session that launches at the size it is watched at isn't resized
+  through a TUI's first screen.
+- **Clear scrollback, on request.** The 🦾 menu's last row, `Clear 🧽`, sends
+  `{ type: "clear_history" }` on the terminal socket; the daemon runs `tmux
+  clear-history` on the pane and forces a capture. The client trims to the
+  frame's `totalLines`, so the stale lines go with the next frame. It discards
+  history, so it is only ever the operator's explicit action, never automatic.
+
+A fold Claude has never been trusted in still shows the dialog once. Accepting
+it on the operator's behalf was considered and left for the operator to decide.

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
@@ -319,6 +321,16 @@ device. Less obvious than it looks:
   both prefer the daemon's Unix socket, recorded as `daemon.sock` since it
   has no address (`connectionLabel`); one token used by any of them is not
   a copy.
+- **Which app a device runs is recorded too** (`app_origin`,
+  `last_app_origin`): the request's `Origin`, first and latest, shown as
+  "via main.brane.organelle.dev", or "via mac.tail1234.ts.net:47443" for a
+  daemon's own bundle. Browsers omit `Origin` on same-origin GETs, so the
+  first request that names a device often cannot name its app; the store
+  writes the first `Origin` it is given, which in practice is the control
+  socket's upgrade, and never overwrites it. It is a label, not a gate:
+  the token is the credential and the daemon accepts any origin
+  (`SECURITY.md`, Authentication), which is what lets a staging hostname
+  or a fork's deployment front the same daemon with nothing to configure.
 - **The address is the only field a token holder cannot choose.** The
   User-Agent and the label are both free text from whoever holds the
   token. So the app never uses the label as a row's title — a row with a
@@ -404,10 +416,18 @@ should guard revoking, as it will guard adding a device, is open: see
 - A revoke does not cut a streaming response already in flight (the Files
   search and `POST /api/absorb`, both NDJSON). Each is bounded work, not a
   listener, and ends on its own.
-- The WebSocket origin check compares only the port for same-origin and
-  accepts any `*.ts.net` host. Nothing rides on it today, since every
-  request must present a token; a passkey verifier will need its own exact
-  origin list.
+- There is no origin check, by design: every request must present a token,
+  and the origin it came from is recorded on the token rather than judged.
+  A passkey verifier will need its own exact origin list
+  ([Passkeys](passkeys.md)); the origins recorded per token are where one
+  would come from.
+- A token is not bound to the origin it was first used from. Pinning it
+  (refusing a different `Origin` afterwards) was considered and left out:
+  Isolate carries the same token between the hosted shell and a daemon's
+  own bundle ([View URLs](view-urls.md)), so the daemon's own origin would need
+  an exemption, and since `?token=` is taken on any method a pin would
+  protect only reads. If a phished link ever needs more than revocation,
+  this is the lever (claude-wh3d2hz2:20, point 4).
 - Fold registration treats a loopback peer as the operator's shell, so a
   forwarder to 127.0.0.1 (`tailscale serve`, an SSH tunnel) would make a
   remote caller look local.