@appsoftwareltd/etherpk-mcp 0.8.0 → 0.8.2

package/dist/main.js

@@ -3,7 +3,7 @@ import { createInterface } from "node:readline/promises";
 import { availableParallelism, homedir, hostname, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
-import { access, chmod, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { access, chmod, lstat, mkdir, readFile, readdir, realpath, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { x25519 } from "@noble/curves/ed25519.js";
 import "@noble/hashes/argon2.js";
@@ -29,9 +29,12 @@ import { languages } from "@codemirror/language-data";
 import MarkdownIt from "markdown-it";
 import katex from "katex";
 import Mustache from "mustache";
+import { lookup } from "node:dns";
+import { request } from "node:https";
+import { BlockList, isIP } from "node:net";
 var package_default = {
 	name: "@appsoftwareltd/etherpk-mcp",
-	version: "0.8.0",
+	version: "0.8.2",
 	license: "Elastic-2.0",
 	description: "EtherPK Headless Client: an MCP server over a synced knowledge graph, run beside the agent on the user's own machine.",
 	type: "module",
@@ -52,20 +55,20 @@ var package_default = {
 		"@huggingface/tokenizers": "0.2.0",
 		"@lezer/highlight": "^1.2.3",
 		"@lezer/markdown": "^1.6.4",
-		"@modelcontextprotocol/sdk": "^1.30.0",
-		"@noble/curves": "^2.2.0",
-		"@noble/hashes": "^2.2.0",
+		"@modelcontextprotocol/sdk": "1.30.0",
+		"@noble/curves": "2.2.0",
+		"@noble/hashes": "2.2.0",
 		"@sqlite.org/sqlite-wasm": "3.53.0-build1",
 		"fake-indexeddb": "^6.2.5",
 		"katex": "^0.17.0",
-		"lib0": "^0.2.117",
+		"lib0": "0.2.117",
 		"markdown-it": "15.0.2",
 		"mermaid": "^11.16.1",
 		"mustache": "4.2.0",
 		"playwright-core": "1.59.1",
-		"y-protocols": "^1.0.7",
+		"y-protocols": "1.0.7",
 		"yaml": "^2.9.0",
-		"yjs": "^13.6.31",
+		"yjs": "13.6.31",
 		"zod": "^4.3.6"
 	},
 	devDependencies: {
@@ -632,7 +635,9 @@ function createSyncApi(deps) {
 		});
 		if (!res.ok) {
 			const body = await res.json().catch(() => null);
-			throw new SyncApiError((typeof body?.error === "object" ? body.error.message : body?.code) ?? `HTTP ${res.status}`, res.status, body?.code, body?.retryable === true);
+			const nested = typeof body?.error === "object" && body.error !== null ? body.error : null;
+			const code = nested?.code ?? body?.code;
+			throw new SyncApiError(nested?.message ?? body?.code ?? `HTTP ${res.status}`, res.status, code, body?.retryable === true);
 		}
 		return await res.json();
 	}
@@ -671,8 +676,14 @@ function createSyncApi(deps) {
 			method: "PUT",
 			body: JSON.stringify({ publicKey })
 		}),
-		getIdentityByEmail: (email) => call(`/api/v1/sync/identity?email=${encodeURIComponent(email)}`).catch((e) => {
-			if (e instanceof SyncApiError && (e.status === 404 || e.status === 409)) return null;
+		getIdentityByEmail: (graphId, email) => call("/api/v1/sync/identity/lookup", {
+			method: "POST",
+			body: JSON.stringify({
+				graphId,
+				email
+			})
+		}).catch((e) => {
+			if (e instanceof SyncApiError && e.status === 404) return null;
 			throw e;
 		}),
 		createInvite: (graphId, inviteeEmail, sealedKeyring) => call("/api/v1/sync/invites", {
@@ -685,6 +696,7 @@ function createSyncApi(deps) {
 		}),
 		listInvites: () => call("/api/v1/sync/invites").then((r) => r.invites),
 		acceptInvite: (id) => call(`/api/v1/sync/invites/${id}/accept`, { method: "POST" }).then((r) => r.graphId),
+		withdrawInvite: (id) => call(`/api/v1/sync/invites/${id}`, { method: "DELETE" }),
 		graphMembers: (graphId) => call(`/api/v1/sync/graphs/${graphId}/members`).then((r) => r.members),
 		leaveGraph: (graphId) => call(`/api/v1/sync/graphs/${graphId}/leave`, { method: "POST" }),
 		deleteGraph: (graphId) => call(`/api/v1/sync/graphs/${graphId}`, { method: "DELETE" }),
@@ -782,6 +794,36 @@ function createSyncTokenSource(mint, opts) {
 	};
 }
 //#endregion
+//#region src/connection-errors.ts
+/** Socket and TLS error codes Node's fetch reports as the cause of "fetch failed". */
+var TLS_CODES = new Set([
+	"ERR_SSL_WRONG_VERSION_NUMBER",
+	"EPROTO",
+	"CERT_HAS_EXPIRED",
+	"DEPTH_ZERO_SELF_SIGNED_CERT",
+	"SELF_SIGNED_CERT_IN_CHAIN",
+	"UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+	"ERR_TLS_CERT_ALTNAME_INVALID"
+]);
+/**
+* Why connecting to a Sync Server failed, in terms a person can act on, or null for a failure
+* this does not recognise. The first mistakes a login makes - the EtherPK app's address in place
+* of the server's, a wrong or revoked token, https against a plain-HTTP server, a mistyped host -
+* otherwise read as "HTTP 404", "Unauthorized" or "fetch failed".
+*/
+function describeConnectionFailure(error, syncServer) {
+	if (error instanceof SyncApiError) {
+		if (error.status === 404 && error.message === "HTTP 404") return `${syncServer} is not a Sync Server (it may be the EtherPK app). Use the Sync Server address shown in EtherPK under a synced graph's Settings > Agents.`;
+		if (error.status === 401) return `${syncServer} did not accept the access token: it may be revoked, expired or mistyped. Create one at ${syncServer}/account/tokens and run login again.`;
+		return null;
+	}
+	if (error instanceof TypeError && error.message === "fetch failed") {
+		const code = error.cause?.code;
+		return `Could not connect to ${syncServer}: ${code === "ENOTFOUND" ? "the host was not found. Check the address." : code === "ECONNREFUSED" ? "the connection was refused. Check the address and that the server is running." : typeof code === "string" && TLS_CODES.has(code) ? "the secure connection failed. Check whether the server uses https or http." : `it did not answer (${typeof code === "string" ? code : "no reason given"}).`}`;
+	}
+	return null;
+}
+//#endregion
 //#region src/account.ts
 /**
 * The account side of the [[Headless Client]]: the same REST bridge and vault the browser uses,
@@ -803,7 +845,13 @@ function createHeadlessAccount(config) {
 /** Resolve the PAT to its principal; a graph-scoped or revoked token fails here, in words. */
 async function connectAccount(config) {
 	const account = createHeadlessAccount(config);
-	const me = await account.api.me();
+	let me;
+	try {
+		me = await account.api.me();
+	} catch (error) {
+		const described = describeConnectionFailure(error, config.syncServer);
+		throw described ? new Error(described, { cause: error }) : error;
+	}
 	return {
 		...account,
 		principal: {
@@ -2572,7 +2620,7 @@ function createSchema(db) {
 	db.exec(SCHEMA$1);
 	db.run("INSERT OR IGNORE INTO index_metadata (key, value) VALUES ('active_generation', 1)");
 	db.run("INSERT OR IGNORE INTO index_metadata (key, value) VALUES ('revision', 0)");
-	db.exec(`PRAGMA user_version = 12`);
+	db.exec(`PRAGMA user_version = 13`);
 }
 function activeIndexGeneration(db) {
 	return db.all("SELECT value FROM index_metadata WHERE key = 'active_generation'")[0]?.value ?? 1;
@@ -2593,7 +2641,7 @@ function advanceIndexRevision(db) {
 */
 function isUsableIndex(db) {
 	try {
-		return db.all("PRAGMA user_version")[0]?.user_version === 12;
+		return db.all("PRAGMA user_version")[0]?.user_version === 13;
 	} catch {
 		return false;
 	}
@@ -2644,8 +2692,12 @@ function hashText(text) {
 function isTextSearchable(block) {
 	return !containsCipherFence(block.text);
 }
-/** Write one document's derived rows under an already-established page id. */
+/**
+* Write one document's derived rows under an already-established page id. Returns the text of
+* every row it put into the text index, which `ingestOne` compares with what it replaced.
+*/
 function insertDerived(db, pageId, doc) {
+	const searchable = [];
 	for (const alias of doc.aliases) db.run("INSERT INTO aliases (page_id, alias_key, display) VALUES (?,?,?)", [
 		pageId,
 		conceptKey$1(alias),
@@ -2683,7 +2735,10 @@ function insertDerived(db, pageId, doc) {
 			b.label,
 			b.text
 		]);
-		if (isTextSearchable(b) && b.localId < 1048576) db.run("INSERT INTO block_fts (rowid, text) VALUES (?,?)", [pageId * BLOCK_FTS_STRIDE + b.localId, b.text]);
+		if (isTextSearchable(b) && b.localId < 1048576) {
+			db.run("INSERT INTO block_fts (rowid, text) VALUES (?,?)", [pageId * BLOCK_FTS_STRIDE + b.localId, b.text]);
+			searchable.push(b.text);
+		}
 	}
 	for (const l of links) db.run("INSERT INTO links (page_id, concept, concept_key, line, line_text, match_start, match_end, block_local_id) VALUES (?,?,?,?,?,?,?,?)", [
 		pageId,
@@ -2721,6 +2776,7 @@ function insertDerived(db, pageId, doc) {
 		hashText(passage.text),
 		passage.text
 	]);
+	return searchable;
 }
 /**
 * Write one document's [[Task Concept]] rows (ADR 0051).
@@ -2765,6 +2821,37 @@ function inTransaction(db, work) {
 		throw err;
 	}
 }
+/**
+* Merge the text index into one segment, which is what removes the words of deleted rows from
+* the database file (ADR 0097).
+*
+* FTS5 deletes by writing a tombstone: the deleted row's terms stay in the segment that holds
+* them until a merge folds segment and tombstone together, and in a graph nobody is editing that
+* can be never. `PRAGMA secure_delete` (index-db-sqlite.ts) zeroes the pages a merge frees, but a
+* segment still in use is not freed. Without a merge, a document protected with content would
+* leave its words readable with `strings` in the browser's OPFS pool and the Headless Client's
+* index file, which is the disk-level reader protection exists to stop.
+*
+* FTS5's own `secure-delete` option would remove the terms on every delete instead. Measured on a
+* 2,400-document index it made an edit's re-index 3.5x slower and a generation swap 12.5 s rather
+* than 0.6 s, for every graph. `optimize` costs about 70 ms there and runs only when protected
+* text may have been left behind: see {@link ingestOne} and {@link purgeIfProtected}.
+*
+* "Protected" here is the index's own flag, `containsCipherFence` anywhere in the text, so it
+* also covers a page holding a fence beside plaintext (text typed after a protected fence, or a
+* quoted example), whose plaintext is indexed until the page is protected whole.
+*/
+function purgeDeletedText(db) {
+	db.run("INSERT INTO block_fts(block_fts) VALUES('optimize')");
+}
+/**
+* After a rebuild: purge when the index now holds any protected document. A rebuild replaces
+* every row, so the old segments may hold the plaintext of a document that was protected since
+* the last build, on this device or another. A graph with no protected document pays nothing.
+*/
+function purgeIfProtected(db, generation) {
+	if (db.all("SELECT 1 AS n FROM pages WHERE generation = ? AND protected = 1 LIMIT 1", [generation]).length > 0) purgeDeletedText(db);
+}
 /** SQLite has no boolean: the `protected` column as stored. */
 function protectedFlag(doc) {
 	return containsCipherFence(doc.text) ? 1 : 0;
@@ -2819,6 +2906,7 @@ function commitIndexRebuild(db, generation) {
 		const revision = advanceIndexRevision(db);
 		const obsolete = db.all("SELECT DISTINCT generation FROM pages WHERE generation <> ?", [generation]).map((row) => row.generation);
 		for (const oldGeneration of obsolete) deleteGeneration(db, oldGeneration);
+		purgeIfProtected(db, generation);
 		return revision;
 	});
 }
@@ -2854,6 +2942,7 @@ function ingestOne(db, doc) {
 		const generation = activeIndexGeneration(db);
 		const found = db.all("SELECT id FROM pages WHERE generation = ? AND concept_key = ?", [generation, key]);
 		let pageId;
+		const leaving = found.length > 0 && protectedFlag(doc) === 1 ? db.all("SELECT text FROM block_fts WHERE rowid >= ? AND rowid < ?", blockFtsRange(found[0].id)).map((row) => row.text) : [];
 		if (found.length > 0) {
 			pageId = found[0].id;
 			db.run("DELETE FROM aliases WHERE page_id = ?", [pageId]);
@@ -2884,7 +2973,8 @@ function ingestOne(db, doc) {
 				protectedFlag(doc)
 			]);
 		}
-		insertDerived(db, pageId, doc);
+		const written = new Set(insertDerived(db, pageId, doc));
+		if (leaving.some((text) => !written.has(text))) purgeDeletedText(db);
 	});
 }
 /** Every concept key that resolves to a real document (canonical name or alias). */
@@ -3215,7 +3305,8 @@ function backlinksFor(db, concept) {
 	const hits = db.all(`SELECT l.page_id, p.concept AS sourceConcept, p.kind AS sourceKind, l.line, l.line_text,
                 l.match_start, l.match_end, l.block_local_id, l.in_title
          FROM links l JOIN pages p ON p.id = l.page_id
-         WHERE p.generation=? AND l.concept_key IN (${placeholders})`, [generation, ...names]);
+         WHERE p.generation=? AND l.concept_key IN (${placeholders})
+         ORDER BY l.page_id, l.line, l.match_start`, [generation, ...names]);
 	const blocksByPage = /* @__PURE__ */ new Map();
 	for (const pid of new Set(hits.map((h) => h.page_id))) {
 		const rows = db.all("SELECT local_id, parent_local_id, ord, kind, depth, done, label, text FROM blocks WHERE page_id=? ORDER BY local_id", [pid]);
@@ -3235,7 +3326,11 @@ function backlinksFor(db, concept) {
 		blocksByPage.set(pid, blocks);
 	}
 	const groups = /* @__PURE__ */ new Map();
+	const places = /* @__PURE__ */ new Set();
 	for (const h of hits) {
+		const place = h.in_title ? `${h.page_id}:title` : h.block_local_id != null ? `${h.page_id}:block:${h.block_local_id}` : `${h.page_id}:line:${h.line}`;
+		if (places.has(place)) continue;
+		places.add(place);
 		let group = groups.get(h.sourceConcept);
 		if (!group) {
 			group = {
@@ -3915,7 +4010,7 @@ function cacheRoot(env) {
 * recovered from a joined path (see there).
 */
 var CACHE_FILE_NAME = `local-cache.v${CACHE_DB_VERSION}.bin`;
-var INDEX_FILE_NAME = `index.v12.sqlite`;
+var INDEX_FILE_NAME = `index.v13.sqlite`;
 var VECTORS_FILE_NAME = `vectors.v1.sqlite`;
 function cacheFile(dir) {
 	return join(dir, CACHE_FILE_NAME);
@@ -3926,7 +4021,7 @@ function indexFile(dir) {
 function vectorsFile(dir) {
 	return join(dir, VECTORS_FILE_NAME);
 }
-function request(req) {
+function request$1(req) {
 	return new Promise((resolve, reject) => {
 		req.onsuccess = () => resolve(req.result);
 		req.onerror = () => reject(req.error);
@@ -3941,7 +4036,7 @@ function done(tx) {
 }
 /** Open the cache database the sync engine already created; never creates or upgrades it. */
 async function openCacheDb() {
-	const db = await request(indexedDB.open(CACHE_DB, CACHE_DB_VERSION));
+	const db = await request$1(indexedDB.open(CACHE_DB, CACHE_DB_VERSION));
 	for (const store of CACHE_STORES) if (!db.objectStoreNames.contains(store)) {
 		db.close();
 		throw new Error(`Local Cache database has no "${store}" store; open the graph cache before restoring it.`);
@@ -3979,7 +4074,7 @@ async function captureLocalCache(graphId) {
 	try {
 		const tx = db.transaction([...CACHE_STORES], "readonly");
 		const rows = {};
-		for (const store of CACHE_STORES) rows[store] = (await request(tx.objectStore(store).getAll())).filter((row) => row.graphId === graphId).map(withStandaloneBuffers);
+		for (const store of CACHE_STORES) rows[store] = (await request$1(tx.objectStore(store).getAll())).filter((row) => row.graphId === graphId).map(withStandaloneBuffers);
 		await done(tx);
 		return {
 			version: CACHE_DB_VERSION,
@@ -4241,6 +4336,65 @@ async function removeCacheRoot(env) {
 		force: true
 	});
 }
+var GRAPH_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+* The account a synced graph's cache was written for. Cache directories are keyed by server host
+* and graph id, not by account, and two agents with their own `ETHERPK_MCP_CONFIG` can sign in as
+* different accounts on one server and share the cache root. The stamp is what lets one of them
+* tidy only its own caches.
+*/
+var OWNER_FILE = "owner.json";
+/** Record which account's graph this cache holds. Written when a synced graph is opened. */
+async function stampGraphCacheOwner(dir, principalId) {
+	await mkdir(dir, {
+		recursive: true,
+		mode: 448
+	});
+	await writeFile(join(dir, OWNER_FILE), `${JSON.stringify({ principalId })}\n`, { mode: 384 });
+}
+/** The account a cache directory was stamped for, or null (none, or unreadable). */
+async function graphCacheOwner(dir) {
+	try {
+		const { principalId } = JSON.parse(await readFile(join(dir, OWNER_FILE), "utf8"));
+		return typeof principalId === "string" ? principalId : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Remove this account's cached graphs of one server that the server no longer lists for it: a
+* graph deleted, left or taken away since this machine last served it. Its cache is the graph's
+* plaintext, and without this it would stay on disk until `logout`. `listed` must be the
+* server's own answer: a failed listing must not reach here, or every cached graph would go.
+*
+* Only directories named as a graph id and stamped for `principalId` are touched. Another
+* account's cache under the same root (its unacknowledged edits included) is not this account's
+* to drop, and a cache written before the stamp existed is left for `logout`. Returns the ids
+* removed.
+*/
+async function removeUnlistedGraphCaches(env, serverBaseUrl, principalId, listed) {
+	const keep = new Set([...listed].map((id) => id.toLowerCase()));
+	const hostDir = dirname(graphCacheDir(env, serverBaseUrl, "x"));
+	let entries;
+	try {
+		entries = await readdir(hostDir, { withFileTypes: true });
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	}
+	const removed = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory() || !GRAPH_ID.test(entry.name) || keep.has(entry.name.toLowerCase())) continue;
+		const dir = join(hostDir, entry.name);
+		if (await graphCacheOwner(dir) !== principalId) continue;
+		await rm(dir, {
+			recursive: true,
+			force: true
+		});
+		removed.push(entry.name);
+	}
+	return removed;
+}
 /** Remove one server's persisted graphs (logout of that server while others stay). */
 async function removeServerCache(env, serverBaseUrl) {
 	await rm(dirname(graphCacheDir(env, serverBaseUrl, "x")), {
@@ -4730,6 +4884,20 @@ var entitlementLimitsSchema = z.strictObject({
 	assetBytes: z.int().nonnegative(),
 	assetChunks: z.int().nonnegative()
 });
+/**
+* Set, and only ever `true`, while the Billing Account's subscription has a payment outstanding
+* (Stripe `past_due` or `unpaid`). It explains a `grace` or `read_only` status as a failed
+* payment rather than an ended plan, so the Client can say "fix your payment" instead of "your
+* subscription has ended". Issuers omit it otherwise, which keeps every other statement readable
+* by a Sync Server whose strict schema predates the field.
+*/
+var paymentOverdueSchema = z.literal(true).optional();
+/**
+* When the Billing Account's trial ends, set only while the trial runs, so the Client and the Sync
+* portal can say "Trial, ends 7 Oct" as the Billing page does. Omitted otherwise, as
+* `paymentOverdue` is.
+*/
+var trialEndsAtSchema = z.iso.datetime({ offset: true }).optional();
 var serviceEntitlementSchema = z.strictObject({
 	eventId: z.uuid(),
 	issuer: httpsUrl,
@@ -4746,6 +4914,8 @@ var serviceEntitlementSchema = z.strictObject({
 	]),
 	plan: z.string().min(1).max(64),
 	limits: entitlementLimitsSchema,
+	paymentOverdue: paymentOverdueSchema,
+	trialEndsAt: trialEndsAtSchema,
 	effectiveAt: z.iso.datetime({ offset: true }),
 	expiresAt: z.iso.datetime({ offset: true })
 }).refine(({ effectiveAt, expiresAt }) => Date.parse(expiresAt) > Date.parse(effectiveAt), {
@@ -4771,14 +4941,18 @@ z.strictObject({
 		id: z.uuid(),
 		email: z.email().nullable(),
 		name: z.string().min(1).nullable(),
-		image: httpsUrl.nullable()
+		image: httpsUrl.nullable(),
+		emailVerified: z.boolean().optional()
 	}),
 	authentication: syncAuthenticationSchema,
+	invitesNeedVerifiedEmail: z.boolean().optional(),
 	clientUrl: httpsUrl.optional(),
 	entitlement: z.strictObject({
 		plan: z.string().min(1).max(64),
 		status: serviceEntitlementSchema.shape.status,
 		limits: entitlementLimitsSchema,
+		paymentOverdue: paymentOverdueSchema,
+		trialEndsAt: trialEndsAtSchema,
 		usage: z.strictObject({
 			ownedGraphs: z.int().nonnegative(),
 			ownedStorageBytes: z.int().nonnegative()
@@ -4800,6 +4974,19 @@ var quotaErrorResponseSchema = z.strictObject({
 	ownerPrincipalId: z.uuid().optional(),
 	retryable: z.literal(true)
 });
+z.strictObject({
+	eventId: z.uuid(),
+	issuer: httpsUrl,
+	audience: z.literal("urn:etherpk:sync-identity"),
+	subject: z.string().min(1).max(256),
+	revision: z.int().positive(),
+	disabled: z.boolean(),
+	deleted: z.boolean(),
+	credentialsRevokedAt: z.iso.datetime({ offset: true }).nullable(),
+	email: z.email().optional(),
+	emailVerified: z.boolean().optional(),
+	issuedAt: z.iso.datetime({ offset: true })
+});
 var SYNC_PROTOCOL_LIMITS = Object.freeze({
 	maxMessageBytes: 12 * 1024 * 1024,
 	maxEnvelopeBytes: 8 * 1024 * 1024,
@@ -5012,6 +5199,7 @@ function serverMessageSchema(limits) {
 			code: z.enum(SYNC_ERROR_CODES),
 			message: z.string().min(1).max(256),
 			docId: uuid.optional(),
+			outboxId: uuid.optional(),
 			currentGeneration: generation.optional(),
 			quotaCode: quotaErrorCodeSchema.optional(),
 			retryable: z.boolean().optional()
@@ -5166,6 +5354,9 @@ var ASSET_CHUNK_PLAINTEXT_BYTES = 4 * 1024 * 1024;
 function assetChunkCount(size) {
 	return Math.max(1, Math.ceil(size / ASSET_CHUNK_PLAINTEXT_BYTES));
 }
+var DAY = 24 * (60 * 6e4);
+365 * DAY, 30 * DAY, 7 * DAY;
+Number.MAX_SAFE_INTEGER;
 //#endregion
 //#region ../client/src/lib/sync/state-vector.ts
 /**
@@ -5207,6 +5398,10 @@ var REMOTE = Symbol("etherpk-remote");
 var CACHE_SEED = Symbol("etherpk-cache-seed");
 /** Structural lifecycle changes which must never be mistaken for a user's edit. */
 var SUPPRESSED = Symbol("etherpk-suppressed");
+/** Health that says the bytes are not this document's, so neither text nor emptiness is real. */
+function contentBlocked(health) {
+	return health === "key-unavailable" || health === "ciphertext-corrupt";
+}
 function newSyncCompletion() {
 	let resolvePromise;
 	let rejectPromise;
@@ -5293,6 +5488,10 @@ function createDocSync(deps) {
 	let pendingSnapshot;
 	/** A read-back failed: the next idle uploads a fresh snapshot whatever the tail size. */
 	let snapshotRetryWanted = false;
+	/** Tell the graph the queue changed; see `DocSyncDeps.onQueueChange`. */
+	function queueChanged() {
+		if (!destroyed) deps.onQueueChange?.();
+	}
 	function requestCatchup(afterSeq) {
 		if (!catchupActive) {
 			if (catchupCompletion.settled) catchupCompletion = newSyncCompletion();
@@ -5379,6 +5578,7 @@ function createDocSync(deps) {
 	}
 	async function transmit(operation) {
 		await persistTask(() => persist.markAttempt(operation.outboxId, now()));
+		if (durableQueue[0]?.outboxId !== operation.outboxId) return;
 		if (operation.kind === "delete") {
 			send({
 				type: "delete",
@@ -5439,6 +5639,7 @@ function createDocSync(deps) {
 			lastAttemptAt: null
 		};
 		durableQueue.push(durable);
+		queueChanged();
 		if (operation.kind === "resurrect") lifecycleState = "resurrecting";
 		await transmit(durable);
 	}
@@ -5692,6 +5893,7 @@ function createDocSync(deps) {
 				baseline.destroy();
 			} else lastSyncedSnapshot = Y.snapshot(doc);
 			if (lifecycleState === "seeding") lifecycleState = "active";
+			queueChanged();
 		},
 		async receive(message) {
 			switch (message.type) {
@@ -5727,6 +5929,7 @@ function createDocSync(deps) {
 						scheduleAutomaticCompaction();
 					}
 					durableQueue.shift();
+					queueChanged();
 					send({
 						type: "ack_confirm",
 						outboxId: message.outboxId
@@ -5757,6 +5960,7 @@ function createDocSync(deps) {
 							}
 							await persist.purge();
 							durableQueue = [];
+							queueChanged();
 							boundarySnapshots.clear();
 							recoveredDirtyTokens.clear();
 							activeDirtyToken = void 0;
@@ -5822,6 +6026,7 @@ function createDocSync(deps) {
 				seeding = false;
 			}
 			for (const operation of durableQueue.splice(0)) await persist.discard(operation.outboxId);
+			queueChanged();
 			boundarySnapshots.clear();
 			lastSyncedSnapshot = Y.snapshot(doc);
 			const operation = {
@@ -5847,6 +6052,7 @@ function createDocSync(deps) {
 				attemptCount: 0,
 				lastAttemptAt: null
 			});
+			queueChanged();
 			await transmit(durableQueue[0]);
 		},
 		lifecycle: () => lifecycleState,
@@ -5854,6 +6060,7 @@ function createDocSync(deps) {
 		async staleGeneration(currentGeneration) {
 			syncHealth = "generation-stale";
 			for (const operation of durableQueue.splice(0)) await persist.discard(operation.outboxId);
+			queueChanged();
 			boundarySnapshots.clear();
 			documentGeneration = currentGeneration;
 			lastSeq = 0;
@@ -5874,6 +6081,12 @@ function createDocSync(deps) {
 			await sendAwareness([doc.clientID]);
 		},
 		isIdle: () => durableQueue.length === 0 && !debounceTimer && !drainPromise,
+		unsentOperations: () => durableQueue.length,
+		retryUnsent() {
+			if (destroyed) return;
+			if (durableQueue[0]) detached(transmit(durableQueue[0]));
+			else detached(requestDrain());
+		},
 		destroy() {
 			destroyed = true;
 			boundarySnapshots.clear();
@@ -6063,6 +6276,29 @@ function createPresenceSession(identity, options = {}) {
 		}
 	};
 }
+var RECONNECT_CAP_MS = 3e4;
+/** The wait before reconnect attempt `attempt` (1 for the first retry). */
+function reconnectDelayMs(attempt, random = Math.random) {
+	const exponent = Math.min(Math.max(0, attempt - 1), 16);
+	const ceiling = Math.min(RECONNECT_CAP_MS, 500 * 2 ** exponent);
+	return Math.floor(random() * ceiling);
+}
+/**
+* How long a graph waits before sending a write the Sync Server refused on a quota again: a
+* lapsed plan, a storage allowance, or a plan the server could not confirm. The refusal is an
+* answer, not an outage, so the schedule is slower than a reconnect's: the ceiling doubles from
+* ten seconds to two minutes. Half of it is fixed and half drawn below it, so a refused client
+* is never back within milliseconds and a crowd refused together spreads out. `round` counts
+* the retries already made for this refusal, from 1. The workspace also retries at once when the
+* person comes back to the tab, which is when a restarted plan usually shows.
+*/
+var REFUSAL_RETRY_BASE_MS = 1e4;
+var REFUSAL_RETRY_CAP_MS = 12e4;
+function refusalRetryDelayMs(round, random = Math.random) {
+	const exponent = Math.min(Math.max(0, round - 1), 16);
+	const ceiling = Math.min(REFUSAL_RETRY_CAP_MS, REFUSAL_RETRY_BASE_MS * 2 ** exponent);
+	return Math.floor(ceiling / 2 + random() * (ceiling / 2));
+}
 //#endregion
 //#region ../client/src/lib/document/quick-notes.ts
 /** A hard ceiling, so a corrupt or hostile list cannot swamp the View or the root doc. */
@@ -6475,16 +6711,65 @@ function graphThemeFromFiles(id, name, files, origin, now = /* @__PURE__ */ new
 *
 * The transport is injected (a `connect(url)` factory) so this unit-tests without real sockets.
 */
-/** Reconnect after a dropped socket (simple; backoff tuned later). */
-var RECONNECT_MS = 50;
-/** Retry after a token mint failed - a server round trip, so slower than a reconnect. */
-var TOKEN_RETRY_MS = 2e3;
+/** The HTTP status a token source's refusal carries (SyncApiError, ManagedTokenError), if any. */
+function refusalStatus(error) {
+	const status = typeof error === "object" && error !== null ? error.status : void 0;
+	return typeof status === "number" ? status : void 0;
+}
+/** How long activity changes are gathered before listeners hear them: an import acks thousands. */
+var ACTIVITY_COALESCE_MS = 50;
 /** Internal signal: a watermark request is safe to repeat on the next socket generation. */
 var WatermarkConnectionInterruptedError = class extends Error {};
+/**
+* The relay did not answer in time: the socket reads open, but nothing reaches the server, as on a
+* connection that dropped without closing. Named so a caller can say "can't reach the Sync Server"
+* rather than repeat the protocol's words.
+*/
+var RelayUnansweredError = class extends Error {};
 function createGraphSync(deps) {
 	const engines = /* @__PURE__ */ new Map();
 	const retained = new Map([[deps.rootDocId, 1]]);
 	const retiring = /* @__PURE__ */ new Set();
+	/**
+	* Batch walks holding an engine: one count per `seedDocsFromCache` or `readyDocs` not yet
+	* matched by a `retireDocs`. Walks overlap - a publish's read, the Local Mirror's pass and
+	* the index's catch-up can all be over the same document - so a count decides retirement.
+	* With a plain flag, the first walk to finish would retire the engine while another still
+	* waited on its catch-up; the catch-up's completion would destroy it, the waiter's
+	* `caughtUpDoc` would resolve, and the waiter would read the empty engine created in its
+	* place (a cold `etherpk-mcp publish` would read every page as empty and "settled").
+	*/
+	const batchHolds = /* @__PURE__ */ new Map();
+	function holdForBatch(docIds) {
+		for (const docId of docIds) {
+			if (docId === deps.rootDocId) continue;
+			batchHolds.set(docId, (batchHolds.get(docId) ?? 0) + 1);
+		}
+	}
+	/**
+	* Wait for a held batch's cache reads. The holds stay taken whether or not they succeed: the
+	* caller releases the batch it asked for, once, in its own `finally`. Releasing here as well
+	* would release a failed batch twice, and the second release would take the hold of another
+	* walk over the same document.
+	*/
+	async function awaitHeld(docIds) {
+		await Promise.all(docIds.map((docId) => readied.get(docId) ?? Promise.resolve()));
+	}
+	/** One hold per document back; an engine no walk holds or retains is retired once idle. */
+	function releaseBatch(docIds) {
+		for (const docId of docIds) {
+			if (docId === deps.rootDocId) continue;
+			const holds = (batchHolds.get(docId) ?? 0) - 1;
+			if (holds > 0) {
+				batchHolds.set(docId, holds);
+				continue;
+			}
+			batchHolds.delete(docId);
+			if (retained.has(docId)) continue;
+			retiring.add(docId);
+			retireEngineIfIdle(docId);
+		}
+	}
 	const presenceSession = deps.presence ? createPresenceSession({
 		name: deps.presence.name,
 		color: deps.presence.color,
@@ -6496,6 +6781,42 @@ function createGraphSync(deps) {
 	let socket;
 	let open = false;
 	let disposed = false;
+	/** Set once access has ended for good; nothing reconnects after it. */
+	let lost = null;
+	/** See `SyncActivity.connection`. */
+	let connection = "connecting";
+	/** Documents whose engines hold unacknowledged outbox operations, kept by `onQueueChange`. */
+	const unsentDocs = /* @__PURE__ */ new Set();
+	/**
+	* Write refusals. The relay answers a refused append, delete or resurrect with `quota_denied`
+	* naming the document and operation, and acknowledges nothing: the operation stays at the
+	* head of that document's outbox, and without a retry the document would stay stalled until
+	* a reload even after the allowance came back. `refusedDocs` are the documents to send
+	* again; empty when a server too old to name them refused.
+	*/
+	let refusal = null;
+	const refusedDocs = /* @__PURE__ */ new Set();
+	/** Bumped by every refusal, so `awaitAcked` can tell one of its own writes from an older one. */
+	let refusalCount = 0;
+	let refusalRounds = 0;
+	let refusalTimer;
+	const refusalDelay = deps.refusalRetryDelayMs ?? ((round) => refusalRetryDelayMs(round));
+	const activityListeners = /* @__PURE__ */ new Set();
+	let activityTimer;
+	const snapshotActivity = () => ({
+		connection,
+		unsentDocuments: unsentDocs.size,
+		refusal
+	});
+	function activityChanged() {
+		if (disposed || activityTimer || activityListeners.size === 0) return;
+		activityTimer = setTimeout(() => {
+			activityTimer = void 0;
+			if (disposed) return;
+			const current = snapshotActivity();
+			for (const listener of activityListeners) listener(current);
+		}, ACTIVITY_COALESCE_MS);
+	}
 	/**
 	* Set when the Sync Server turned out to speak another protocol version. The session then
 	* stops for good: every reconnect would meet the same server, and nothing either side
@@ -6506,6 +6827,10 @@ function createGraphSync(deps) {
 		if (!disposed) deps.onError?.(error instanceof Error ? error : new Error(String(error)));
 	};
 	const outboundSnapshots = [];
+	/** Documents whose operation this socket has sent and the relay has not answered, to its outbox id. */
+	const operationsInFlight = /* @__PURE__ */ new Map();
+	/** Each document's operation waiting for room in {@link OPERATION_WINDOW}, oldest first. */
+	const operationsWaiting = /* @__PURE__ */ new Map();
 	const foregroundCatchups = [];
 	const backgroundCatchups = [];
 	let catchupInFlight;
@@ -6523,6 +6848,7 @@ function createGraphSync(deps) {
 	function waitForCurrentConnection() {
 		if (open && socket) return Promise.resolve();
 		if (disposed) return Promise.reject(/* @__PURE__ */ new Error("the graph sync session was disposed"));
+		if (lost) return Promise.reject(/* @__PURE__ */ new Error("access to this graph has ended"));
 		if (protocolMismatch) return Promise.reject(protocolMismatch);
 		return new Promise((resolve, reject) => {
 			connectionWaiters.add({
@@ -6541,7 +6867,7 @@ function createGraphSync(deps) {
 					const requestId = crypto.randomUUID();
 					const timer = setTimeout(() => {
 						watermarkRequests.delete(requestId);
-						reject(/* @__PURE__ */ new Error("the sync relay did not answer a watermark check"));
+						reject(new RelayUnansweredError("the sync relay did not answer a watermark check"));
 					}, 15e3);
 					watermarkRequests.set(requestId, {
 						resolve,
@@ -6555,7 +6881,7 @@ function createGraphSync(deps) {
 					}));
 				});
 			} catch (error) {
-				if (error instanceof WatermarkConnectionInterruptedError && !disposed) continue;
+				if (error instanceof WatermarkConnectionInterruptedError && !disposed && !lost) continue;
 				throw error;
 			}
 		}
@@ -6617,6 +6943,37 @@ function createGraphSync(deps) {
 		pumpCatchups();
 		retireEngineIfIdle(completedDocId);
 	}
+	/**
+	* Send a document's operation within the window, or hold it until an answer makes room. A
+	* document's newer operation replaces one still waiting (the engine sends only its head).
+	*/
+	function sendOperation(docId, message) {
+		ackRoute.set(message.outboxId, docId);
+		if (!open || !socket) return;
+		if (!operationsInFlight.has(docId) && operationsInFlight.size >= 128) {
+			operationsWaiting.set(docId, message);
+			return;
+		}
+		operationsWaiting.delete(docId);
+		operationsInFlight.set(docId, message.outboxId);
+		sendNow(message);
+	}
+	/**
+	* The relay answered `docId`'s operation, by acking or refusing it: its place in the window
+	* goes to the longest-waiting one. `outboxId`, when the answer names one, must be the
+	* operation in flight; an answer to an older one frees nothing.
+	*/
+	function operationAnswered(docId, outboxId) {
+		const inFlight = operationsInFlight.get(docId);
+		if (inFlight === void 0 || outboxId !== void 0 && inFlight !== outboxId) return;
+		operationsInFlight.delete(docId);
+		for (const [waitingDocId, waiting] of operationsWaiting) {
+			if (!open || !socket || operationsInFlight.size >= 128) return;
+			operationsWaiting.delete(waitingDocId);
+			operationsInFlight.set(waitingDocId, waiting.outboxId);
+			sendNow(waiting);
+		}
+	}
 	function rawSend(message) {
 		if (message.type === "catchup") {
 			queueCatchup(message);
@@ -6652,7 +7009,7 @@ function createGraphSync(deps) {
 		presenceDetach.delete(docId);
 	}
 	function retireEngineIfIdle(docId) {
-		if (docId === deps.rootDocId || retained.has(docId) || !retiring.has(docId)) return;
+		if (docId === deps.rootDocId || retained.has(docId) || batchHolds.has(docId) || !retiring.has(docId)) return;
 		if (catchupInFlight?.docId === docId || foregroundCatchups.some((request) => request.docId === docId) || backgroundCatchups.some((request) => request.docId === docId)) return;
 		const candidate = engines.get(docId);
 		if (!candidate || !candidate.isIdle()) return;
@@ -6660,6 +7017,7 @@ function createGraphSync(deps) {
 		detachPresence(docId);
 		candidate.destroy();
 		engines.delete(docId);
+		unsentDocs.delete(docId);
 		readied.delete(docId);
 		syncEnabled.delete(docId);
 		performanceRecorder.mark("sync.engine.count", {
@@ -6667,6 +7025,69 @@ function createGraphSync(deps) {
 			subscriptions: retained.size
 		});
 	}
+	function noteQueue(docId) {
+		const e = engines.get(docId);
+		if (e && e.unsentOperations() > 0) unsentDocs.add(docId);
+		else unsentDocs.delete(docId);
+		activityChanged();
+	}
+	/**
+	* The relay refused a write on a quota. A refused snapshot is not a stalled write - the relay
+	* still holds the document's log, and the engine uploads another at a later idle - so only a
+	* refused outbox operation (named by its outbox id), or a refusal a server too old to name
+	* anything sent, counts.
+	*/
+	function noteRefusal(message) {
+		if (message.docId && !message.outboxId) return;
+		if (message.docId) refusedDocs.add(message.docId);
+		refusal = message.quotaCode ? { quotaCode: message.quotaCode } : {};
+		refusalCount += 1;
+		scheduleRefusalRetry();
+		activityChanged();
+	}
+	function scheduleRefusalRetry() {
+		if (refusalTimer || disposed || lost) return;
+		refusalTimer = setTimeout(() => {
+			refusalTimer = void 0;
+			refusalRounds += 1;
+			resendRefused();
+		}, refusalDelay(refusalRounds + 1));
+	}
+	/** Send each refused document's head operation again; the relay applies an outbox id once. */
+	function resendRefused() {
+		if (disposed || lost || !open) return;
+		const docIds = refusedDocs.size > 0 ? [...refusedDocs] : [...unsentDocs];
+		for (const docId of docIds) {
+			const e = engines.get(docId);
+			if (!e || e.unsentOperations() === 0) {
+				refusedDocs.delete(docId);
+				continue;
+			}
+			e.retryUnsent();
+		}
+		if (refusedDocs.size === 0 && unsentDocs.size === 0) clearRefusal();
+	}
+	/** Whether every document with unsent operations is one the server refused. */
+	function everyUnsentRefused() {
+		if (unsentDocs.size === 0) return false;
+		if (refusedDocs.size === 0) return true;
+		for (const docId of unsentDocs) if (!refusedDocs.has(docId)) return false;
+		return true;
+	}
+	/** An ack: the server accepted a write, so that document is refused no longer. */
+	function writeAccepted(docId) {
+		if (!refusal) return;
+		refusedDocs.delete(docId);
+		if (refusedDocs.size === 0) clearRefusal();
+	}
+	function clearRefusal() {
+		refusal = null;
+		refusedDocs.clear();
+		refusalRounds = 0;
+		clearTimeout(refusalTimer);
+		refusalTimer = void 0;
+		activityChanged();
+	}
 	function engine(docId, synchronize = true) {
 		let e = engines.get(docId);
 		if (!e) {
@@ -6675,7 +7096,10 @@ function createGraphSync(deps) {
 				graphId: deps.graphId,
 				keyring: deps.keyring,
 				send: (message) => {
-					if (message.type === "append" || message.type === "delete" || message.type === "resurrect") ackRoute.set(message.outboxId, docId);
+					if (message.type === "append" || message.type === "delete" || message.type === "resurrect") {
+						sendOperation(docId, message);
+						return;
+					}
 					rawSend(message);
 				},
 				persist: deps.cache.docCache(docId, docId === deps.rootDocId ? "root" : "document"),
@@ -6683,6 +7107,7 @@ function createGraphSync(deps) {
 				collectRowWhen: docId === deps.rootDocId ? void 0 : deps.collectRowWhen,
 				onError: reportError,
 				onIdle: () => queueMicrotask(() => retireEngineIfIdle(docId)),
+				onQueueChange: () => noteQueue(docId),
 				catchupPriority: () => {
 					return retained.has(docId) ? "foreground" : "background";
 				}
@@ -6779,6 +7204,11 @@ function createGraphSync(deps) {
 	function stopForProtocolMismatch(serverVersion) {
 		if (protocolMismatch) return;
 		protocolMismatch = new SyncProtocolMismatchError(serverVersion);
+		connection = "ended";
+		clearTimeout(reconnectTimer);
+		clearTimeout(refusalTimer);
+		refusalTimer = void 0;
+		activityChanged();
 		reportError(protocolMismatch);
 		for (const waiter of connectionWaiters) waiter.reject(protocolMismatch);
 		connectionWaiters.clear();
@@ -6798,8 +7228,18 @@ function createGraphSync(deps) {
 			continuation: message.hasMore ? 1 : 0
 		});
 		if (message.type === "error") {
+			if (message.code === "membership_revoked") {
+				endAccess({ kind: "membership" });
+				return;
+			}
+			if (message.code === "quota_denied") {
+				if (message.docId) operationAnswered(message.docId, message.outboxId);
+				noteRefusal(message);
+				return;
+			}
 			if (message.code === "stale_generation" && message.docId && message.currentGeneration !== void 0) {
 				if (catchupInFlight?.docId === message.docId) catchupInFlight = void 0;
+				operationAnswered(message.docId);
 				engine(message.docId).staleGeneration(message.currentGeneration);
 				pumpCatchups();
 			}
@@ -6821,7 +7261,13 @@ function createGraphSync(deps) {
 		}
 		if (message.type === "ack") {
 			const docId = ackRoute.get(message.outboxId);
-			if (docId) engine(docId).receive(message).then(() => ackRoute.delete(message.outboxId)).catch(report);
+			if (docId) {
+				operationAnswered(docId, message.outboxId);
+				engine(docId).receive(message).then(() => {
+					ackRoute.delete(message.outboxId);
+					writeAccepted(docId);
+				}).catch(report);
+			}
 			return;
 		}
 		if (message.type === "catchup_batch") {
@@ -6831,20 +7277,78 @@ function createGraphSync(deps) {
 		engine(message.docId).receive(message).catch(report);
 	}
 	/**
+	* Forget everything that belonged to one socket generation. Durable IndexedDB rows, not these
+	* entries, determine outstanding work and replay on the next open, which resubscribes every
+	* retained document.
+	*/
+	function forgetSocketGeneration() {
+		subscribed.clear();
+		ackRoute.clear();
+		operationsInFlight.clear();
+		operationsWaiting.clear();
+		catchupInFlight = void 0;
+		foregroundCatchups.length = 0;
+		backgroundCatchups.length = 0;
+		for (const pending of watermarkRequests.values()) {
+			clearTimeout(pending.timer);
+			pending.reject(new WatermarkConnectionInterruptedError());
+		}
+		watermarkRequests.clear();
+	}
+	let attempts = 0;
+	let openedAt = 0;
+	let forceToken = false;
+	let credentialRefusals = 0;
+	let reconnectTimer;
+	const retryDelay = deps.retryDelayMs ?? ((attempt) => reconnectDelayMs(attempt));
+	function scheduleConnect(delayMs) {
+		if (disposed || lost || protocolMismatch) return;
+		clearTimeout(reconnectTimer);
+		reconnectTimer = setTimeout(connect, delayMs);
+	}
+	function backOff() {
+		attempts += 1;
+		scheduleConnect(retryDelay(attempts));
+	}
+	/** Stop for good: close the socket, never reconnect, and tell the owner once. */
+	function endAccess(loss) {
+		if (lost || disposed) return;
+		lost = loss;
+		connection = "ended";
+		clearTimeout(reconnectTimer);
+		clearTimeout(refusalTimer);
+		refusalTimer = void 0;
+		activityChanged();
+		const current = socket;
+		socket = void 0;
+		open = false;
+		forgetSocketGeneration();
+		current?.close();
+		for (const waiter of connectionWaiters) waiter.reject(/* @__PURE__ */ new Error("access to this graph has ended"));
+		connectionWaiters.clear();
+		deps.onAccessLost?.(loss);
+	}
+	/**
 	* A token is fetched for EVERY connect, never captured: the source re-mints when the
-	* held token nears expiry, so a socket that drops an hour in still reconnects. Sends
+	* held token nears expiry, so a socket that drops an hour in still reconnects.
 	* Encrypted appends issued while the token is in flight remain in IndexedDB and replay
 	* on open. Only rebuildable snapshot uploads use a volatile queue.
 	*/
 	function connect() {
-		if (disposed || protocolMismatch) return;
-		deps.token().then((token) => {
-			if (disposed) return;
+		if (disposed || lost || protocolMismatch) return;
+		const force = forceToken;
+		forceToken = false;
+		deps.token(force ? { force: true } : void 0).then((token) => {
+			if (disposed || lost) return;
 			const s = deps.connect(`${deps.relayUrl}?token=${encodeURIComponent(token)}`);
 			socket = s;
 			s.onOpen(() => {
-				if (disposed || socket !== s) return;
+				if (disposed || lost || socket !== s) return;
 				open = true;
+				connection = "open";
+				activityChanged();
+				openedAt = Date.now();
+				credentialRefusals = 0;
 				resolveFirstOpen?.();
 				for (const waiter of connectionWaiters) waiter.resolve();
 				connectionWaiters.clear();
@@ -6865,24 +7369,45 @@ function createGraphSync(deps) {
 				}
 			});
 			s.onMessage(handleMessage);
-			s.onClose(() => {
+			s.onClose((event) => {
 				if (socket !== s) return;
+				const upFor = open ? Date.now() - openedAt : 0;
 				open = false;
 				socket = void 0;
-				subscribed.clear();
-				ackRoute.clear();
-				catchupInFlight = void 0;
-				foregroundCatchups.length = 0;
-				backgroundCatchups.length = 0;
-				for (const pending of watermarkRequests.values()) {
-					clearTimeout(pending.timer);
-					pending.reject(new WatermarkConnectionInterruptedError());
+				forgetSocketGeneration();
+				if (disposed || lost || protocolMismatch) return;
+				connection = "reconnecting";
+				activityChanged();
+				if (event?.code === 4403) {
+					endAccess({ kind: "membership" });
+					return;
+				}
+				if (upFor >= 1e4) attempts = 0;
+				if (event?.code === 4401) {
+					forceToken = true;
+					credentialRefusals += 1;
+					if (credentialRefusals === 1) {
+						scheduleConnect(0);
+						return;
+					}
 				}
-				watermarkRequests.clear();
-				if (!disposed && !protocolMismatch) setTimeout(connect, RECONNECT_MS);
+				backOff();
 			});
-		}, () => {
-			if (!disposed) setTimeout(connect, TOKEN_RETRY_MS);
+		}, (error) => {
+			if (disposed || lost) return;
+			const status = refusalStatus(error);
+			if (status === 401) {
+				endAccess({
+					kind: "credentials",
+					cause: error
+				});
+				return;
+			}
+			if (status === 403) {
+				endAccess({ kind: "membership" });
+				return;
+			}
+			backOff();
 		});
 	}
 	connect();
@@ -7061,21 +7586,17 @@ function createGraphSync(deps) {
 			await readied.get(docId);
 		},
 		async seedDocsFromCache(docIds) {
+			holdForBatch(docIds);
 			const batch = docIds.map((docId) => engine(docId, false));
-			await Promise.all(docIds.map((docId) => readied.get(docId) ?? Promise.resolve()));
+			await awaitHeld(docIds);
 			return batch.map((entry) => entry.doc);
 		},
 		async readyDocs(docIds) {
+			holdForBatch(docIds);
 			for (const docId of docIds) engine(docId);
-			await Promise.all(docIds.map((docId) => readied.get(docId) ?? Promise.resolve()));
-		},
-		retireDocs(docIds) {
-			for (const docId of docIds) {
-				if (docId === deps.rootDocId || retained.has(docId)) continue;
-				retiring.add(docId);
-				retireEngineIfIdle(docId);
-			}
+			await awaitHeld(docIds);
 		},
+		retireDocs: releaseBatch,
 		firstCatchupPageDoc: (docId) => engine(docId).firstCatchupPage(),
 		caughtUpDoc: (docId) => engine(docId).caughtUp(),
 		async docsNeedingCatchup(docIds) {
@@ -7102,12 +7623,24 @@ function createGraphSync(deps) {
 			};
 		},
 		isConnected: () => open,
+		activity: snapshotActivity,
+		onActivity(listener) {
+			activityListeners.add(listener);
+			return () => activityListeners.delete(listener);
+		},
+		retryRefused() {
+			if (!refusal) return;
+			clearTimeout(refusalTimer);
+			refusalTimer = void 0;
+			resendRefused();
+		},
 		async flushAll({ onProgress } = {}) {
 			const all = [...engines.values()];
 			let flushed = 0;
 			await Promise.all(all.map((e) => e.flush().then(() => onProgress?.(++flushed, all.length))));
 		},
 		async awaitAcked({ onProgress, signal, stallMs = 3e4 } = {}) {
+			const refusalsBefore = refusalCount;
 			const initial = await deps.cache.countPending();
 			if (initial === 0) return {
 				settled: true,
@@ -7135,13 +7668,19 @@ function createGraphSync(deps) {
 							settled: true,
 							outstanding: 0
 						});
+						if (refusal && (refusalCount > refusalsBefore || everyUnsentRefused())) return finish({
+							settled: false,
+							outstanding: current,
+							refused: refusal
+						});
 						if (signal?.aborted) return finish({
 							settled: false,
 							outstanding: current
 						});
 						if (Date.now() - lastProgressAt >= stallMs) return finish({
 							settled: false,
-							outstanding: current
+							outstanding: current,
+							...refusal ? { refused: refusal } : {}
 						});
 						timer = setTimeout(poll, POLL_MS);
 					} catch (error) {
@@ -7159,14 +7698,21 @@ function createGraphSync(deps) {
 			activeEngines: engines.size,
 			retainedDocuments: retained.size
 		}),
+		endAccess,
+		accessLoss: () => lost,
 		dispose() {
 			disposed = true;
+			clearTimeout(reconnectTimer);
+			clearTimeout(refusalTimer);
+			clearTimeout(activityTimer);
+			activityListeners.clear();
 			socket?.close();
 			for (const detach of presenceDetach.values()) detach();
 			presenceDetach.clear();
 			for (const e of engines.values()) e.destroy();
 			engines.clear();
 			retiring.clear();
+			batchHolds.clear();
 			syncEnabled.clear();
 			foregroundCatchups.length = 0;
 			backgroundCatchups.length = 0;
@@ -7646,7 +8192,10 @@ function nodeTransport(url) {
 		close: () => ws.close(),
 		onOpen: (cb) => ws.addEventListener("open", () => cb()),
 		onMessage: (cb) => ws.addEventListener("message", (e) => cb(String(e.data))),
-		onClose: (cb) => ws.addEventListener("close", () => cb())
+		onClose: (cb) => ws.addEventListener("close", (event) => cb({
+			code: event.code,
+			reason: event.reason
+		}))
 	};
 }
 //#endregion
@@ -9003,6 +9552,32 @@ function assetHashFromName(fileName) {
 		ext: (match[3] ?? "").toLowerCase()
 	};
 }
+/**
+* Whether a decoded asset name is one file inside `assets/`, and so safe to join onto a folder.
+*
+* An asset reference comes from a document, and a document can come from a collaborator, an
+* import or an agent, so the name it decodes to is untrusted: `../assets/..%2Fpages%2FSecret.md`
+* decodes to a path that leaves `assets/`. Every place that turns a reference into a file path
+* (the asset stores, the publisher's bundle) checks this first, before any directory adapter
+* or site writer sees the name.
+*/
+function isSafeAssetName(name) {
+	if (!isSingleFileName(name)) return false;
+	for (const char of name) {
+		const code = char.codePointAt(0) ?? 0;
+		if (code < 32 || code === 127) return false;
+	}
+	return true;
+}
+/**
+* Whether `name` is one entry of a directory rather than a path: not empty, not `.` or `..`, and
+* free of separators and NUL. What a directory adapter requires of every name it is handed, which
+* is looser than {@link isSafeAssetName}: a file already on disk may carry other odd characters.
+*/
+function isSingleFileName(name) {
+	if (name === "" || name === "." || name === "..") return false;
+	return !name.includes("/") && !name.includes("\\") && !name.includes("\0");
+}
 //#endregion
 //#region ../client/src/lib/storage/fs/asset-store.ts
 /**
@@ -9036,6 +9611,20 @@ var IMAGE_EXTS = new Set([
 ]);
 /** A doc-relative asset reference: optional `../` hops, then `assets/<name>`. */
 var ASSET_REF$1 = /^(?:\.\.\/)*assets\/(.+)$/;
+/**
+* An asset could not be fetched just now: the connection failed, or the server answered with a
+* status that means "try again". It says nothing about whether the file exists, so something
+* showing the file asks again rather than calling it missing. `status` is the server's answer,
+* absent when the connection failed before there was one.
+*/
+var AssetUnavailableError = class extends Error {
+	name = "AssetUnavailableError";
+	status;
+	constructor(message, options = {}) {
+		super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+		this.status = options.status;
+	}
+};
 /** Split a file name into its stem and lower-cased extension (`''` ext when there is none). */
 function splitNameExt(fileName) {
 	const dot = fileName.lastIndexOf(".");
@@ -9103,11 +9692,22 @@ var MIME_TYPES = {
 function mimeTypeForExt(ext) {
 	return MIME_TYPES[ext.replace(/^\./, "").toLowerCase()] ?? "";
 }
-/** The on-disk name referenced by a doc-relative asset ref, or `null` if `ref` is not an asset reference. */
+/**
+* The on-disk name referenced by a doc-relative asset ref, or `null` if `ref` is not an asset
+* reference. A reference whose name decodes to anything but one file inside `assets/`, or does not
+* decode at all, is not one: it can never name a file on disk (see `isSafeAssetName`).
+*/
 function assetNameFromRef(ref) {
 	const clean = ref.split(/[?#]/)[0];
 	const match = ASSET_REF$1.exec(clean);
-	return match ? decodeURIComponent(match[1]) : null;
+	if (!match) return null;
+	let name;
+	try {
+		name = decodeURIComponent(match[1]);
+	} catch {
+		return null;
+	}
+	return isSafeAssetName(name) ? name : null;
 }
 /**
 * The markdown to embed a saved asset: an inline image, or a plain link that downloads on click.
@@ -9464,6 +10064,25 @@ async function deleteGraphTheme(adapter, id) {
 * Pure: no store, no editor. The YAML rules (what counts as a block, how it parses) come from
 * `storage/fs`, shared with the scan and the editor's analysis, so there is one rule.
 */
+/** What the block claims. An unterminated block is not a block, as everywhere else. */
+function frontmatterIdentity(text) {
+	const span = frontmatterSpan(text);
+	const data = span ? parseBlock$2(span.body) : {};
+	if (data === null) return {
+		title: null,
+		aliases: [],
+		hasAliasesKey: false,
+		hasBlock: true,
+		readable: false
+	};
+	return {
+		title: titleOf(data),
+		aliases: aliasesOf({ data }),
+		hasAliasesKey: "aliases" in data,
+		hasBlock: span !== null,
+		readable: true
+	};
+}
 function titleOf(data) {
 	const title = data.title;
 	return typeof title === "string" && title.trim() !== "" ? title : null;
@@ -9532,6 +10151,19 @@ function withFrontmatterIdentity(text, patch, options = {}) {
 	if (wantAliases.length > 0 && !("aliases" in data)) next.aliases = wantAliases;
 	return `---\n${serialise(next)}---\n${text.slice(span.end)}`;
 }
+/**
+* `after` - a writer's rewrite of `before` - with the document's aliases carried into the block
+* the rewrite added. A writer that gives a document its first block, as Publish does when it adds
+* `public:`, must not make the document claim fewer aliases than it has: a block with no
+* `aliases:` line claims none, and the next edit to it would clear them (ADR 0061). Only a Server
+* Backend has aliases without a block; on a Filesystem Backend they are read from the saved file,
+* so `aliases` is empty there provided the caller wrote pending edits before reading them
+* (`rewriteFrontmatter` flushes first). A block `before` already had is left as the writer left it.
+*/
+function withAliasesInAddedBlock(before, after, aliases) {
+	if (aliases.length === 0 || frontmatterSpan(before) !== null || frontmatterSpan(after) === null) return after;
+	return withFrontmatterIdentity(after, { aliases });
+}
 /** The block's YAML as a plain object, or null when it is malformed or not an object. */
 function parseBlock$2(yaml) {
 	try {
@@ -9979,6 +10611,31 @@ async function refuseProtectedMerges(plan, isProtected) {
 	return plan;
 }
 /**
+* Refuse a plan whose steps would rewrite a [[Frontmatter]] block that does not parse. A
+* Filesystem Backend rebuilds each renamed document's block, and a merge survivor's, from its
+* parsed data, which is empty for such a block, so every key it holds would be lost from the file:
+* the only copy. `textOf` gives a document's current text (an open buffer, else its file), or
+* null for a name with no document behind it.
+*/
+async function refuseUnreadableBlocks(plan, textOf) {
+	if (plan.refusal) return plan;
+	for (const step of renameSteps(plan)) for (const concept of step.merges ? [step.from, step.into] : [step.from]) {
+		const text = await textOf(concept);
+		if (text === null || frontmatterIdentity(text).readable) continue;
+		return {
+			...plan,
+			refusal: unreadableBlockRefusal(plan.direct.from, concept)
+		};
+	}
+	return plan;
+}
+/** Why `renamed` cannot be renamed: the block of `unreadable` (itself, or a page the rename rewrites) does not parse. */
+function unreadableBlockRefusal(renamed, unreadable) {
+	const fix = "Fix the block (a property written twice, or a line left half typed) and rename again.";
+	if (conceptKey(renamed) === conceptKey(unreadable)) return `“${renamed}” cannot be renamed while its frontmatter is not valid YAML: renaming rewrites the block, and what it holds would be lost. ${fix}`;
+	return `“${renamed}” cannot be renamed while the frontmatter of “${unreadable}”, which the rename rewrites, is not valid YAML: what it holds would be lost. ${fix}`;
+}
+/**
 * A step merges when a DIFFERENT document already answers to the target name - by title or by
 * alias - and the source has a document to join to it. Renaming onto yourself (a pure
 * re-casing, or onto one of your own aliases) is neither. A source with no document landing
@@ -10303,6 +10960,7 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 			await settled(openDoc);
 		}
 		const { text } = await adapter.read(entry.subdir, entry.fileName);
+		if (!frontmatterIdentity(text).readable) throw new Error(unreadableBlockRefusal(step.from, entry.concept));
 		const fm = parseFrontmatter(text);
 		let aliases = aliasesOf(fm);
 		let body = fm.body;
@@ -10313,7 +10971,9 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 		const targetEntry = step.merges ? registry.get(conceptKey(step.into)) : void 0;
 		const survivor = targetEntry && targetEntry.key !== entry.key ? targetEntry : void 0;
 		if (survivor) {
-			const existingFm = parseFrontmatter((await adapter.read(survivor.subdir, survivor.fileName)).text);
+			const existing = await adapter.read(survivor.subdir, survivor.fileName);
+			if (!frontmatterIdentity(existing.text).readable) throw new Error(unreadableBlockRefusal(step.from, survivor.concept));
+			const existingFm = parseFrontmatter(existing.text);
 			const merged = mergeDocuments({
 				body: existingFm.body,
 				aliases: aliasesOf(existingFm)
@@ -10422,6 +11082,29 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 		if (doc.dirty) runSave(doc);
 		await settled(doc);
 	}
+	/**
+	* The registry entry `target` names: a document by its own name, else by one of its aliases
+	* (ADR 0061), as a bookmark or a Recents entry can carry a renamed page's old name. A page's own
+	* name outranks another page's alias of the same name, as the index resolves it.
+	*/
+	function entryNamed(target) {
+		const key = conceptKey(target);
+		const own = registry.get(key);
+		if (own) return own;
+		for (const entry of registry.values()) if (entry.aliases.some((alias) => conceptKey(alias) === key)) return entry;
+	}
+	/** The open document `target` names, opening it if it is not; throws when nothing has that name. */
+	function openDocNamed(target) {
+		const existing = open.get(conceptKey(target));
+		if (existing) return existing;
+		const entry = entryNamed(target);
+		if (!entry) throw new DocumentNotFoundError(target);
+		const opened = open.get(entry.key);
+		if (opened) return opened;
+		const doc = makeOpenDoc(entry.key === conceptKey(target) ? target : entry.concept, entry);
+		open.set(entry.key, doc);
+		return doc;
+	}
 	function makeOpenDoc(target, entry) {
 		const doc = {
 			key: entry.key,
@@ -10525,17 +11208,10 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 	}
 	return {
 		open(target) {
-			const key = conceptKey(target);
-			const existing = open.get(key);
-			if (existing) return existing.handle;
-			const entry = registry.get(key);
-			if (!entry) throw new DocumentNotFoundError(target);
-			const doc = makeOpenDoc(target, entry);
-			open.set(key, doc);
-			return doc.handle;
+			return openDocNamed(target).handle;
 		},
 		async whenReady(target) {
-			await (open.get(conceptKey(target)) ?? (this.open(target), open.get(conceptKey(target))))?.ready;
+			await openDocNamed(target).ready;
 		},
 		async scan() {
 			await adapter.ensureSkeleton();
@@ -10684,7 +11360,7 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 			return concept;
 		},
 		async planRename(from, to, referencingDocuments) {
-			return refuseProtectedMerges(planRename$1({
+			return refuseUnreadableBlocks(await refuseProtectedMerges(planRename$1({
 				from,
 				to,
 				kind: registry.get(conceptKey(from))?.kind ?? null,
@@ -10698,6 +11374,12 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 				const other = registry.get(conceptKey(concept));
 				if (!other) return false;
 				return documentProtection(open.get(other.key)?.buffer ?? (await adapter.read(other.subdir, other.fileName)).text).kind === "document";
+			}), async (concept) => {
+				const other = registry.get(conceptKey(concept));
+				if (!other) return null;
+				const openDoc = open.get(other.key);
+				if (openDoc) await settled(openDoc);
+				return (await adapter.read(other.subdir, other.fileName)).text;
 			});
 		},
 		async renamePage(from, to, options) {
@@ -10760,6 +11442,11 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 			if (!doc) return;
 			await saveNow(doc);
 		},
+		async flushAll() {
+			await Promise.all([...open.values()].map(saveNow));
+			const unwritten = [...open.values()].filter((doc) => doc.dirty).map((doc) => doc.target);
+			if (unwritten.length > 0) throw new Error(`Edits to ${unwritten.join(", ")} could not be written to the folder yet, so it does not hold them. Try again once they are saved.`);
+		},
 		async dispose() {
 			await Promise.all([...open.values()].map(saveNow));
 			open.clear();
@@ -10960,10 +11647,6 @@ async function reachedWithin(promise, timeoutMs) {
 		if (timer) clearTimeout(timer);
 	}
 }
-/** Health that says the bytes are not this document's, so neither text nor emptiness is real. */
-function contentBlocked(health) {
-	return health === "key-unavailable" || health === "ciphertext-corrupt";
-}
 function createServerDocumentStore(graph, options) {
 	const registry = graph.registry();
 	/** Engines created between yields while snapshotting — small enough to keep frames free. */
@@ -10974,6 +11657,9 @@ function createServerDocumentStore(graph, options) {
 	const changeListeners = /* @__PURE__ */ new Set();
 	const docsChangedListeners = /* @__PURE__ */ new Set();
 	const removedListeners = /* @__PURE__ */ new Set();
+	const renamedListeners = /* @__PURE__ */ new Set();
+	/** docId to the name it had when first seen renamed from elsewhere, and its latest name. */
+	const renamesFromElsewhere = /* @__PURE__ */ new Map();
 	const resurrectionClaims = /* @__PURE__ */ new Map();
 	let disposed = false;
 	/** Whether the encrypted registry has been read to its terminal relay page this session. */
@@ -10993,9 +11679,14 @@ function createServerDocumentStore(graph, options) {
 	*/
 	async function materialise(docIds, timeoutMs) {
 		const unique = [...new Set(docIds)];
-		const release = () => graph.retireDocs(unique);
+		const held = [];
+		const release = () => graph.retireDocs(held);
 		try {
-			for (let start = 0; start < unique.length; start += ENGINE_BATCH) await graph.readyDocs(unique.slice(start, start + ENGINE_BATCH));
+			for (let start = 0; start < unique.length; start += ENGINE_BATCH) {
+				const batch = unique.slice(start, start + ENGINE_BATCH);
+				held.push(...batch);
+				await graph.readyDocs(batch);
+			}
 			const connected = graph.isConnected();
 			const behind = new Set(connected ? await graph.docsNeedingCatchup(unique) : []);
 			const unconfirmed = [];
@@ -11052,11 +11743,18 @@ function createServerDocumentStore(graph, options) {
 		});
 		return out;
 	}
+	/**
+	* Every name a document answers to, to its docId. A page's own name outranks another page's
+	* alias of the same name, whatever order the registry lists them in, as the index resolves it.
+	*/
 	function currentDocIds() {
 		const out = /* @__PURE__ */ new Map();
+		registry.forEach((entry, docId) => out.set(conceptKey(conceptOf(entry)), docId));
 		registry.forEach((entry, docId) => {
-			out.set(conceptKey(conceptOf(entry)), docId);
-			for (const alias of entry.aliases ?? []) out.set(conceptKey(alias), docId);
+			for (const alias of entry.aliases ?? []) {
+				const key = conceptKey(alias);
+				if (!out.has(key)) out.set(key, docId);
+			}
 		});
 		return out;
 	}
@@ -11065,25 +11763,43 @@ function createServerDocumentStore(graph, options) {
 			const nextRegistry = currentRegistryIdentities();
 			const changedDocIds = [...new Set([...knownRegistry.keys(), ...nextRegistry.keys()])].filter((docId) => !sameIdentity(knownRegistry.get(docId), nextRegistry.get(docId)));
 			if (changedDocIds.length === 0) return;
+			const restored = event.transaction.origin === CACHE_SEED;
+			const fromElsewhere = !restored && !event.transaction.local;
 			const additions = [];
+			const renames = [];
 			let additionsOnly = true;
 			for (const docId of changedDocIds) {
 				const before = knownRegistry.get(docId);
 				const after = nextRegistry.get(docId);
+				if (fromElsewhere && before && after && before.concept !== after.concept) renames.push({
+					docId,
+					from: before.concept,
+					to: after.concept
+				});
 				if (before || !after) {
 					additionsOnly = false;
 					continue;
 				}
 				additions.push(after.concept);
 			}
+			const renamedAway = new Set(renames.map((rename) => conceptKey(rename.from)));
 			const next = currentConcepts();
-			for (const [key, concept] of known) if (!next.has(key)) removedListeners.forEach((l) => l(concept));
+			for (const [key, concept] of known) if (!next.has(key) && !renamedAway.has(key)) removedListeners.forEach((l) => l(concept));
 			known = next;
 			docIdsByConcept = currentDocIds();
 			knownRegistry = nextRegistry;
 			docsChangedListeners.forEach((l) => l());
-			if (additionsOnly) for (const concept of additions) changeListeners.forEach((listener) => listener({ concept }));
+			if (!restored) if (additionsOnly) for (const concept of additions) changeListeners.forEach((listener) => listener({ concept }));
 			else changeListeners.forEach((listener) => listener());
+			for (const { docId, from, to } of renames) {
+				const first = renamesFromElsewhere.get(docId)?.from ?? from;
+				if (first === to) renamesFromElsewhere.delete(docId);
+				else renamesFromElsewhere.set(docId, {
+					from: first,
+					to
+				});
+				renamedListeners.forEach((listener) => listener(from, to));
+			}
 			for (const [docId, change] of event.changes.keys) {
 				if (change.action !== "delete") continue;
 				const claimed = resurrectionClaims.get(docId);
@@ -11361,6 +12077,18 @@ function createServerDocumentStore(graph, options) {
 			}
 			return out;
 		},
+		async docsBehind(docIds, timeoutMs = COLD_CONTENT_TIMEOUT_MS) {
+			if (disposed || !graph.isConnected()) return null;
+			if (docIds.length === 0) return [];
+			let timer;
+			try {
+				return await Promise.race([graph.docsNeedingCatchup(docIds).catch(() => null), new Promise((resolve) => {
+					timer = setTimeout(() => resolve(null), timeoutMs);
+				})]);
+			} finally {
+				if (timer) clearTimeout(timer);
+			}
+		},
 		async confirmRegistry(timeoutMs = 5e3) {
 			if (registryConfirmed) return true;
 			if (!graph.isConnected()) return false;
@@ -11375,6 +12103,13 @@ function createServerDocumentStore(graph, options) {
 			removedListeners.add(listener);
 			return () => removedListeners.delete(listener);
 		},
+		onDocumentRenamed(listener) {
+			renamedListeners.add(listener);
+			return () => renamedListeners.delete(listener);
+		},
+		renamesObserved() {
+			return [...renamesFromElsewhere.values()].map((rename) => ({ ...rename }));
+		},
 		onChange(listener) {
 			changeListeners.add(listener);
 			return () => changeListeners.delete(listener);
@@ -11488,11 +12223,16 @@ function createServerDocumentStore(graph, options) {
 				acknowledge: checkpoint.acknowledge
 			};
 		},
-		snapshotDocument(concept) {
+		async snapshotDocument(concept) {
 			const docId = docIdFor(concept);
-			const entry = docId ? registry.get(docId) : void 0;
-			if (!docId || !entry) return null;
-			return indexSnapshotFor(entry, graph.docSync(docId).doc.getText("content").toString());
+			if (!docId || !registry.has(docId)) return null;
+			try {
+				await graph.readyDocs([docId]);
+				const entry = registry.get(docId);
+				return entry ? indexSnapshotFor(entry, graph.docSync(docId).doc.getText("content").toString()) : null;
+			} finally {
+				graph.retireDocs([docId]);
+			}
 		},
 		async compactDocument(target) {
 			const docId = docIdFor(target);
@@ -11759,7 +12499,7 @@ async function withRetry(task, options = {}) {
 		} catch (error) {
 			if (options.signal?.aborted) throw options.signal.reason;
 			if (attempt >= attempts || !shouldRetry(error)) throw error;
-			const full = base * 2 ** (attempt - 1);
+			const full = Math.min(base * 2 ** (attempt - 1), options.maxDelayMs ?? Number.POSITIVE_INFINITY);
 			const wait = Math.round(full / 2 + random() * (full / 2));
 			options.onRetry?.(error, attempt, wait);
 			await sleep(wait, options.signal);
@@ -11849,11 +12589,25 @@ var HttpFailure = class extends Error {
 */
 function isTransient(error) {
 	if (!(error instanceof HttpFailure)) return true;
-	return error.status === 401 || error.status === 408 || error.status === 429 || error.status >= 500;
+	return isTransientStatus(error.status);
+}
+/** "Not your fault, try again": a 401 only once a fresh token has been presented. */
+function isTransientStatus(status) {
+	return status === 401 || status === 408 || status === 429 || status >= 500;
 }
 function kebabStem(name) {
 	return name.replace(/\.[^.]+$/, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "asset";
 }
+/**
+* The MIME type a downloaded asset is given: its extension's, from the same short list the
+* Filesystem Backend uses, or `application/octet-stream`. Never the type recorded in the asset's
+* metadata, which is whatever the uploader's client sent: a collaborator could type an asset
+* `text/html`, and a blob opened in its own tab would then be a same-origin HTML document. The
+* extension is the reference's, the one the viewers are chosen by.
+*/
+function assetTypeFor(ref) {
+	return mimeTypeForExt(extOf(ref)) || "application/octet-stream";
+}
 function extOf(name) {
 	const m = /\.([^.]+)$/.exec(name);
 	return m ? m[1].toLowerCase() : "bin";
@@ -11910,14 +12664,33 @@ function createServerAssetStore(deps) {
 		}, retryOptions);
 	}
 	/**
-	* Fetch, decrypt and reassemble one asset. Both read paths go through here: the mirror
-	* wants the bytes themselves, a viewer wants them behind an object URL.
+	* A read request whose connection failure is a file that cannot be fetched just now, not a
+	* missing one. A cancellation stays a cancellation.
 	*/
-	async function readAssetBytes(ref) {
+	async function readRequest(url, init) {
+		try {
+			return await f(url, init);
+		} catch (error) {
+			if (error instanceof DOMException && error.name === "AbortError") throw error;
+			throw new AssetUnavailableError("The file could not be fetched: the connection failed.", { cause: error });
+		}
+	}
+	/**
+	* Fetch, decrypt and reassemble one asset; both read paths go through here. `null` when the
+	* server has no such asset or refuses it. A failure that says nothing about the asset rejects
+	* with `AssetUnavailableError`: the connection, or a status that means "try again" (a 401
+	* after one fresh token). A file that will not decrypt or parse rejects with that error.
+	*/
+	async function fetchAssetBytes(ref) {
 		const assetId = assetIdFromRef(ref);
 		if (!assetId) return null;
-		const res = await f(`${base}/api/v1/sync/assets/${deps.graphId}/${assetId}`, { headers: { "x-sync-token": await deps.syncToken() } });
-		if (!res.ok) return null;
+		const url = `${base}/api/v1/sync/assets/${deps.graphId}/${assetId}`;
+		let res = await readRequest(url, { headers: { "x-sync-token": await deps.syncToken() } });
+		if (res.status === 401) res = await readRequest(url, { headers: { "x-sync-token": await deps.syncToken({ force: true }) } });
+		if (!res.ok) {
+			if (isTransientStatus(res.status)) throw new AssetUnavailableError(`The sync server could not hand over the file just now (HTTP ${res.status}).`, { status: res.status });
+			return null;
+		}
 		const body = await res.json();
 		const metaPlain = await openSymmetric({
 			keyForEpoch: (id) => keyForEpoch(deps.keyring, id),
@@ -11928,8 +12701,11 @@ function createServerAssetStore(deps) {
 		const perAssetKey = fromBase64Url(metadata.perAssetKey);
 		const parts = [];
 		for (let n = 0; n < body.downloadUrls.length; n++) {
-			const chunkRes = await f(body.downloadUrls[n]);
-			if (!chunkRes.ok) return null;
+			const chunkRes = await readRequest(body.downloadUrls[n]);
+			if (!chunkRes.ok) {
+				if (chunkRes.status !== 401 && isTransientStatus(chunkRes.status)) throw new AssetUnavailableError(`Storage could not hand over the file just now (HTTP ${chunkRes.status}).`, { status: chunkRes.status });
+				return null;
+			}
 			const { plaintext } = await openSymmetric({
 				keyForEpoch: () => perAssetKey,
 				envelope: new Uint8Array(await chunkRes.arrayBuffer()),
@@ -11947,7 +12723,7 @@ function createServerAssetStore(deps) {
 		return {
 			bytes: joined,
 			name: metadata.name,
-			type: metadata.type
+			type: assetTypeFor(ref)
 		};
 	}
 	return {
@@ -12019,7 +12795,7 @@ function createServerAssetStore(deps) {
 						body: chunks[n]
 					});
 				} catch {
-					throw new Error("Uploading to the storage bucket was blocked. The bucket's CORS policy must allow this app's origin - see \"Asset storage\" in the Synced Graphs doc.");
+					throw new Error(typeof navigator !== "undefined" && navigator.onLine === false ? "The connection dropped while uploading to the storage bucket." : "Uploading to the storage bucket was blocked. The bucket's CORS policy must allow this app's origin - see \"Asset storage\" in the Synced Graphs doc.");
 				}
 				if (!r.ok) throw new HttpFailure(r.status, `chunk ${n} upload failed: ${r.status}`);
 				onBytes?.(Math.min(CHUNK_SIZE, bytes.length - n * CHUNK_SIZE));
@@ -12035,9 +12811,9 @@ function createServerAssetStore(deps) {
 			});
 			return saved(assetId, false);
 		},
-		readBytes: readAssetBytes,
+		readBytes: (ref) => fetchAssetBytes(ref).catch((error) => error instanceof AssetUnavailableError && error.status !== void 0 ? null : Promise.reject(error)),
 		async resolve(ref) {
-			const asset = await readAssetBytes(ref);
+			const asset = await fetchAssetBytes(ref);
 			if (!asset) return null;
 			const url = URL.createObjectURL(new Blob([asset.bytes], { type: asset.type }));
 			objectUrls.push(url);
@@ -12079,6 +12855,20 @@ async function listServerAssets(deps) {
 	return assets;
 }
 //#endregion
+//#region ../client/src/lib/sync/write-refusal.ts
+var AGENT_REASONS = {
+	entitlement_inactive: "the graph owner's plan does not allow changes at the moment (a lapsed, unpaid or unconfirmed plan)",
+	owned_storage_limit: "the graph owner's storage allowance is used up"
+};
+/**
+* The Headless Client's refusal, for an agent: the edit was refused, not lost in transit, and it
+* needs no retry from the agent. The connection-loss wording ("will be delivered when the
+* connection recovers") is untrue of a refusal.
+*/
+function writeRefusalForAgent(refusal, outstanding) {
+	return `The Sync Server refused the edit: ${(refusal.quotaCode && AGENT_REASONS[refusal.quotaCode]) ?? "a plan limit was reached"}. ${outstanding === 1 ? "1 operation is held" : `${outstanding} operations are held`} here and sent automatically once the server accepts changes again.`;
+}
+//#endregion
 //#region src/headless-graph.ts
 /**
 * How often the cache and index are exported while a build is running. A build reports
@@ -12197,6 +12987,7 @@ function assembleHeadlessGraph(parts) {
 		publishing: parts.publishing,
 		themes: parts.themes,
 		settle: () => parts.settle(schedulePersist),
+		accessLoss: () => parts.accessLoss?.() ?? null,
 		persist,
 		semantic,
 		semanticOpened: () => semanticOpening ? semanticOpening.catch(() => void 0) : Promise.resolve(void 0),
@@ -12232,6 +13023,7 @@ async function openHeadlessGraph(deps) {
 			...PRESENCE_PALETTE[0]
 		},
 		onError: deps.onError,
+		onAccessLost: deps.onAccessLost,
 		publishName: deps.publishName
 	});
 	const store = createServerDocumentStore(sync, { readyTimeoutMs: deps.readyTimeoutMs });
@@ -12314,6 +13106,7 @@ async function openHeadlessGraph(deps) {
 		return assembleHeadlessGraph({
 			graphId: deps.graphId,
 			name: sync.getMeta().name ?? deps.graphId,
+			accessLoss: () => sync.accessLoss(),
 			store: documents,
 			index,
 			assets,
@@ -12349,6 +13142,12 @@ async function openHeadlessGraph(deps) {
 				const result = await sync.awaitAcked({ stallMs: 1e4 });
 				schedulePersist();
 				if (result.settled) return { settled: true };
+				if (result.refused) return {
+					settled: false,
+					outstanding: result.outstanding,
+					code: "write_refused",
+					message: writeRefusalForAgent(result.refused, result.outstanding)
+				};
 				return {
 					settled: false,
 					outstanding: result.outstanding,
@@ -12626,6 +13425,43 @@ async function openHeadlessFolder(deps) {
 	}
 }
 //#endregion
+//#region ../client/src/lib/sync/recovery-unlock.ts
+/**
+* Unlock with a Recovery Code, checked against the account's vault.
+*
+* A Recovery Code derives the vault's wrap key, and any well-formed code derives *a* key. Caching
+* whatever came out would report a mistyped or retired code as success, and every graph would
+* then fail to open with a message that blamed the keys on the device, next to the control that
+* resets them. The browser and the Headless Client both use this one check: fetch the vault,
+* open it with the derived key, and hand back the vault key only once it has opened.
+*
+* What is returned is the vault key, never the wrap key, as Device Approval caches: it keeps
+* working after the Recovery Code is regenerated on another device.
+*/
+/** The account has no vault yet, so there is nothing for a Recovery Code to open. */
+var NoVaultError = class extends Error {
+	constructor() {
+		super("This account has no encryption keys yet; there is nothing for a Recovery Code to open.");
+		this.name = "NoVaultError";
+	}
+};
+/**
+* @throws RecoveryCodeError when the code is malformed or does not open this account's vault.
+* @throws NoVaultError when the account has no vault.
+* Anything else (the vault could not be fetched) propagates unchanged: it says nothing about the code.
+*/
+async function openVaultWithRecoveryCode(api, code) {
+	const wrapKey = await deriveVaultWrapKey(code);
+	const stored = await api.getVault();
+	if (!stored) throw new NoVaultError();
+	try {
+		return (await openVault(fromBase64Url(stored.vault), wrapKey)).vaultKey;
+	} catch (error) {
+		if (error instanceof EnvelopeError) throw new RecoveryCodeError("That Recovery Code does not open this account’s keys. Check it character by character; only the most recently issued code works.");
+		throw error;
+	}
+}
+//#endregion
 //#region ../client/src/lib/sync/device-approval.ts
 /**
 * Device approval (ADR 0026 flows): unlock a NEW device from an already-unlocked one, so
@@ -12697,18 +13533,66 @@ var ApprovalAbandoned = class extends Error {
 /** Approval rows expire server-side after ten minutes; poll a little longer and then give up. */
 var APPROVAL_TIMEOUT_MS = 11 * 6e4;
 var APPROVAL_POLL_MS = 2e3;
+/** How long a quit waits for the server to cancel the approval before leaving anyway. */
+var CANCEL_TIMEOUT_MS = 5e3;
+/** Shell exit codes for the signals that end a login: 128 plus the signal's number. */
+var SIGNAL_EXIT_CODES = {
+	SIGHUP: 129,
+	SIGINT: 130,
+	SIGTERM: 143
+};
+/**
+* How the approval wait ends early. `r` switches to the Recovery Code; Ctrl-C (a key while the
+* terminal is in raw mode) and SIGINT, SIGTERM or SIGHUP quit. Either way the wait aborts, so it
+* cancels its approval server-side before anything exits: a login left pending showed its stale
+* code in every unlocked tab for ten minutes. `exitCode` is set once the user has quit.
+*/
+function approvalWaitControls() {
+	const abort = new AbortController();
+	let exitCode = null;
+	return {
+		signal: abort.signal,
+		get exitCode() {
+			return exitCode;
+		},
+		onKey(key) {
+			if (key === "r" || key === "R") abort.abort();
+			if (key === "") {
+				exitCode = SIGNAL_EXIT_CODES.SIGINT;
+				abort.abort();
+			}
+		},
+		onSignal(name) {
+			exitCode = SIGNAL_EXIT_CODES[name];
+			abort.abort();
+		}
+	};
+}
+/** A sleep that ends as soon as the signal aborts, so a quit does not wait out the poll interval. */
+function sleepUnlessAborted(ms, signal) {
+	return new Promise((resolve) => {
+		if (signal.aborted) return resolve();
+		const done = () => {
+			clearTimeout(timer);
+			signal.removeEventListener("abort", done);
+			resolve();
+		};
+		const timer = setTimeout(done, ms);
+		signal.addEventListener("abort", done, { once: true });
+	});
+}
 async function unlockByDeviceApproval(api, io) {
 	const request = await beginDeviceApproval(api);
 	const where = io.clientUrl ? `open EtherPK at ${io.clientUrl}` : "open EtherPK in a browser";
 	io.say("");
-	io.say(`To approve this device, ${where} (any page - it need not be a note) signed in to this account`);
-	io.say("with its graphs unlocked. A prompt will show a code; confirm it matches this one:");
+	io.say(`To approve this device, ${where} (any page - it need not be a note), connected to this account`);
+	io.say("with its keys unlocked. A prompt will show a code; confirm it matches this one:");
 	io.say("");
 	io.say(`    ${request.sas}`);
 	io.say("");
 	io.say("Waiting (up to ten minutes)…");
 	const abandon = async () => {
-		await api.cancelDeviceApproval(request.id).catch(() => {});
+		await Promise.race([api.cancelDeviceApproval(request.id).catch(() => {}), new Promise((resolve) => setTimeout(resolve, CANCEL_TIMEOUT_MS).unref())]);
 		throw new ApprovalAbandoned();
 	};
 	const deadline = Date.now() + APPROVAL_TIMEOUT_MS;
@@ -12723,12 +13607,12 @@ async function unlockByDeviceApproval(api, io) {
 	}
 	throw new Error("The approval was not confirmed in time. Run login again.");
 }
-/** Recovery Code → wrap key → open the vault; what comes back is the vault key to cache. */
+/**
+* Recovery Code → wrap key → open the vault; what comes back is the vault key to cache. The same
+* check the browser makes (recovery-unlock.ts): a wrong code is refused as wrong and nothing is cached.
+*/
 async function unlockByRecoveryCode(api, code) {
-	const wrapKey = await deriveVaultWrapKey(normalizeRecoveryCode(code));
-	const stored = await api.getVault();
-	if (!stored) throw new Error("This account has no encryption keys yet; there is nothing for a Recovery Code to open.");
-	return (await openVault(fromBase64Url(stored.vault), wrapKey)).vaultKey;
+	return openVaultWithRecoveryCode(api, code);
 }
 //#endregion
 //#region ../client/src/lib/document/publish/selection.ts
@@ -12848,7 +13732,11 @@ function publicDocumentsInNoPublication(documents, publications) {
 }
 //#endregion
 //#region ../client/src/lib/document/publish/host/site-writer.ts
-/** Stale files are removed only from the places the publisher owns. */
+/**
+* Stale files are removed only from the places the publisher owns. `etherpk-publish.json` is not
+* produced but stays owned, so the first publish after the upgrade deletes the copy an older
+* build left in the folder.
+*/
 function isOwnedPath(path) {
 	if (path.startsWith("assets/") || path.startsWith("theme/")) return true;
 	if (path.includes("/")) return false;
@@ -13509,6 +14397,50 @@ function archiveHtml(journals) {
 	return `<ul class="journal-archive">${journals.map((j) => `<li><time datetime="${escapeHtml$6(j.date ?? "")}">${escapeHtml$6(j.date ?? "")}</time> <a href="${escapeHtml$6(j.url)}">${escapeHtml$6(j.title)}</a>${j.excerpt ? `<p>${escapeHtml$6(j.excerpt)}</p>` : ""}</li>`).join("")}</ul>`;
 }
 //#endregion
+//#region ../client/src/lib/document/publish/diagram-id.ts
+/**
+* Renaming a drawn Mermaid diagram's id, so a published page can carry it.
+*
+* Mermaid renders a diagram under the id it is given and scopes everything else to that id: every
+* rule of its inline `<style>` (`#gk-mermaid-4 .node rect { fill: … }`), its marker definitions
+* (`gk-mermaid-4_flowchart-pointEnd`) and the `url(#…)` references to them, and its accessible
+* title and description ids. The published `<svg>` must keep an id its styles match; without one
+* no rule applies and every node rect takes SVG's default black fill.
+*
+* The host's own id is not good enough to keep as it is. It comes from a render counter, so it
+* changes from one publish to the next (and the browser host reuses the editor's cached drawings),
+* which would rewrite every page with a diagram on every publish; and one drawing is reused for
+* every occurrence of the same source, so a diagram shown twice on a page would put one id there
+* twice. The publisher therefore renames each occurrence to an id of its own choosing.
+*/
+/** The root element's id, or null. Only the opening tag is read. */
+function rootId(svg) {
+	const open = /^\s*<svg\b[^>]*>/.exec(svg)?.[0];
+	if (!open) return null;
+	return /\sid="([^"]+)"/.exec(open)?.[1] ?? null;
+}
+/** The id the inline styles are scoped to, for a drawing whose root has lost its id. */
+function styleScope(svg) {
+	const style = /<style\b[^>]*>([\s\S]*?)<\/style>/.exec(svg)?.[1];
+	if (!style) return null;
+	return /#([A-Za-z][\w-]*)(?=[\s{.,>:])/.exec(style)?.[1] ?? null;
+}
+function escapeRegExp(text) {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* The drawing with its id, and everything scoped to it, renamed to `id`. `id` must be a valid
+* CSS identifier that starts with a letter. A drawing with no id anywhere is returned as it is:
+* nothing in it is scoped, so there is nothing to keep in step.
+*/
+function withDiagramId(svg, id) {
+	const current = rootId(svg);
+	if (current) return svg.replace(new RegExp(`${escapeRegExp(current)}(?![A-Za-z0-9])`, "g"), id);
+	const scope = styleScope(svg);
+	if (!scope) return svg;
+	return svg.replace(new RegExp(`${escapeRegExp(scope)}(?![A-Za-z0-9])`, "g"), id).replace(/^(\s*<svg\b)/, `$1 id="${id}"`);
+}
+//#endregion
 //#region ../client/src/lib/document/code-languages.ts
 /**
 * The grammar for a [[Fenced Code Block]]'s info-string, from the registry the editor nests inside
@@ -13815,15 +14747,22 @@ function wikilinkRule(md, resolve) {
 */
 /** A document-relative asset reference: any number of `../`, `assets/`, the name. */
 var ASSET_REF = /^(?:\.\.\/)*assets\/(.+)$/;
+/**
+* The asset a reference names, decoded, or null when it names none. A name that decodes to
+* anything but one file inside `assets/` is not an asset: it would become a bundle path, and a site
+* folder, outside `assets/` (see `isSafeAssetName`). The link is then left as the author wrote it.
+*/
 function assetNameOf(ref) {
 	const match = ASSET_REF.exec(ref);
 	if (!match) return null;
 	const raw = match[1].split(/[?#]/)[0];
+	let name;
 	try {
-		return decodeURIComponent(raw);
+		name = decodeURIComponent(raw);
 	} catch {
-		return raw;
+		name = raw;
 	}
+	return isSafeAssetName(name) ? name : null;
 }
 function escapeHtml$3(text) {
 	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -14031,7 +14970,7 @@ function linkTargetPattern(excluded = "") {
 * A regex may not repeat a group name, so compose this **once** per pattern. Wrap it in a group of
 * your own where you need the whole link as one capture.
 */
-var MARKDOWN_LINK = `(?<bang>!?)\\[(?<label>[^\\]]*)\\]\\((?<target>${linkTargetPattern()})\\)`;
+var MARKDOWN_LINK = `(?<bang>!?)\\[(?<label>(?:[^\\[\\]]|\\[[^\\[\\]]*\\])*)\\]\\((?<target>${linkTargetPattern()})\\)`;
 /** A match's groups, typed. Every {@link MARKDOWN_LINK} match has all three. */
 function linkGroups(match) {
 	return match.groups;
@@ -14133,6 +15072,24 @@ function contentOf(block) {
 	return first.replace(/^-\s+/, "").trim();
 }
 var WHOLE_LINK = new RegExp(`^${MARKDOWN_LINK}$`);
+/** The schemes an outline link may carry onto a published page; a target with no scheme is a path on the site. */
+var NAV_LINK_SCHEMES = new Set([
+	"http",
+	"https",
+	"mailto"
+]);
+/**
+* An outline link's target, or null when a published page must not carry it. Links in page bodies
+* go through markdown-it's validateLink; the outline is parsed here, so it gets its own rule. The
+* scheme is read after removing the control characters and spaces a browser would ignore, so
+* '\u0001javascript:' is read as javascript.
+*/
+function navLinkTarget(target) {
+	const visible = [...target].filter((c) => c.charCodeAt(0) > 32 && c.charCodeAt(0) !== 127).join("");
+	const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(visible);
+	if (!scheme) return target;
+	return NAV_LINK_SCHEMES.has(scheme[1].toLowerCase()) ? target : null;
+}
 function buildNav(outline, resolver) {
 	const issues = [];
 	function convert(blocks) {
@@ -14166,10 +15123,24 @@ function buildNav(outline, resolver) {
 				const link = WHOLE_LINK.exec(content);
 				if (link && !linkGroups(link).bang) {
 					const { label, target } = linkGroups(link);
+					const href = navLinkTarget(target);
+					if (href === null) {
+						issues.push({
+							level: "warning",
+							code: "nav-link-unsafe",
+							message: `The navigation links "${label}" to a target a published page does not carry (only http, https, mailto and site paths); the entry is shown without its link.`
+						});
+						out.push({
+							label,
+							labelHtml: escapeHtml$1(label),
+							children
+						});
+						continue;
+					}
 					out.push({
 						label,
 						labelHtml: escapeHtml$1(label),
-						href: target,
+						href,
 						external: true,
 						children
 					});
@@ -14533,18 +15504,32 @@ async function publishPublication(source, publication, env, options = {}) {
 		const html = await highlight(fence.lang, fence.code);
 		if (html !== null) highlighted.set(key, html);
 	}
+	let diagramScope = {
+		prefix: "mermaid",
+		n: 0
+	};
+	const scopeDiagrams = (prefix) => {
+		diagramScope = {
+			prefix: prefix.replace(/[^A-Za-z0-9_-]/g, "-"),
+			n: 0
+		};
+	};
 	const renderer = createDocumentRenderer({
 		resolve: resolver.resolve,
 		assetHref: assetHrefOf,
-		mermaidSvg: (src) => mermaidSvg.get(src),
+		mermaidSvg: (src) => {
+			const svg = mermaidSvg.get(src);
+			return svg === void 0 ? void 0 : withDiagramId(svg, `${diagramScope.prefix}_${++diagramScope.n}`);
+		},
 		highlighted: (lang, code) => highlighted.get(`${lang}\n${code}`)
 	});
 	const pages = [];
 	let done = 0;
 	for (const doc of included) {
 		progress("rendering", done++, included.length);
-		const rendered = renderer.render(bodyOf(doc));
 		const slug = slugs.get(conceptKey$1(doc.concept));
+		scopeDiagrams(`mermaid_${slug}`);
+		const rendered = renderer.render(bodyOf(doc));
 		const isHome = doc === homeDoc;
 		const page = {
 			doc,
@@ -14622,7 +15607,10 @@ async function publishPublication(source, publication, env, options = {}) {
 				continue;
 			}
 			customCss += (customCss ? "\n" : "") + fence.code;
-		} else includes.set(slot, renderer.render(body).html);
+		} else {
+			scopeDiagrams(`mermaid__${slot}`);
+			includes.set(slot, renderer.render(body).html);
+		}
 		report.includes.push({
 			name: slot,
 			source: "page",
@@ -14781,7 +15769,7 @@ async function publishPublication(source, publication, env, options = {}) {
 	let assetsDone = 0;
 	for (const [name, from] of wanted) {
 		progress("assets", assetsDone++, wanted.size);
-		const asset = await source.readAsset(`../assets/${name}`);
+		const asset = await source.readAsset(`../assets/${encodeURIComponent(name)}`);
 		if (!asset) {
 			report.assets.missing.push({
 				name,
@@ -14931,6 +15919,8 @@ function themeFilesOfBundled(theme) {
 		files
 	};
 }
+/** Far more files than any theme uses, and a bound on the fetches one publish can trigger. */
+var MAX_URL_THEME_FILES = 500;
 /** Fetch a theme from its manifest URL; every file the manifest lists, relative to it. */
 async function fetchTheme(url, fetchText) {
 	let json;
@@ -14942,10 +15932,12 @@ async function fetchTheme(url, fetchText) {
 	const { manifest, errors } = parseThemeManifest(json);
 	if (!manifest) throw new Error(`The theme at ${url} cannot be used: ${errors.join(" ")}`);
 	if (manifest.files.length === 0) throw new Error(`The theme at ${url} lists no files in its manifest, so nothing can be fetched.`);
+	if (manifest.files.length > MAX_URL_THEME_FILES) throw new Error(`The theme at ${url} lists ${manifest.files.length} files; a theme may list at most ${MAX_URL_THEME_FILES}.`);
 	const base = new URL(url);
 	const files = /* @__PURE__ */ new Map();
 	for (const path of manifest.files) {
 		const fileUrl = new URL(path, base).toString();
+		if (!isThemeFilePath(path) || new URL(fileUrl).origin !== base.origin) throw new Error(`The theme at ${url} lists "${path}", which is not a theme file beside its manifest (layouts/, partials/ or assets/).`);
 		try {
 			files.set(path, await fetchText(fileUrl));
 		} catch (error) {
@@ -14995,9 +15987,10 @@ function createThemeLoader(deps) {
 /** Replace a document's frontmatter block with the one `rewrite` produces, through its live handle. */
 async function rewriteFrontmatter(store, concept, rewrite) {
 	await store.whenReady?.(concept);
+	await store.flushDocument?.(concept);
 	const handle = store.open(concept);
 	const text = handle.getText();
-	const next = rewrite(text);
+	const next = withAliasesInAddedBlock(text, rewrite(text), registryAliases(store, concept));
 	if (next === text) return false;
 	const before = frontmatterSpan(text)?.end ?? 0;
 	const after = frontmatterSpan(next)?.end ?? 0;
@@ -15009,6 +16002,11 @@ async function rewriteFrontmatter(store, concept, rewrite) {
 	await store.flushDocument?.(concept);
 	return true;
 }
+/** The document's aliases as its store's registry holds them, found by its identity key. */
+function registryAliases(store, concept) {
+	const key = conceptKey(concept);
+	return store.listDocuments?.().find((entry) => entry.key === key)?.aliases ?? [];
+}
 /** A publication id from a title: `Docs Site` → `docs-site`. */
 function suggestPublicationId(title) {
 	return publishSlug(title);
@@ -15117,7 +16115,6 @@ async function runPublish(publication, deps) {
 		code: "documents-unsettled",
 		message: `${deps.unsettled.length} document${deps.unsettled.length === 1 ? " has" : "s have"} not finished syncing to this device and ${deps.unsettled.length === 1 ? "was" : "were"} left out: ${deps.unsettled.slice(0, 5).join(", ")}${deps.unsettled.length > 5 ? "…" : ""}. Publish again once sync has caught up.`
 	});
-	if (report.ok) bundle.set("etherpk-publish.json", `${JSON.stringify(report, null, 2)}\n`);
 	return {
 		report,
 		bundle,
@@ -15262,7 +16259,6 @@ async function openDiagramRenderer(env) {
 					const { svg } = await m.render(renderId, text);
 					const el = new DOMParser().parseFromString(svg, "text/html").querySelector("svg");
 					if (!el) throw new Error("Mermaid produced no diagram.");
-					el.removeAttribute("id");
 					el.setAttribute("role", "img");
 					return el.outerHTML;
 				} finally {
@@ -15277,6 +16273,150 @@ async function openDiagramRenderer(env) {
 	};
 }
 //#endregion
+//#region src/public-fetch.ts
+/**
+* Fetching text from the public internet, and nowhere else: the only network reads a tool makes
+* with an address it did not choose itself (a theme published at a URL, and every file its
+* manifest lists). The URL comes from a document or a tool argument, so a collaborator or a
+* prompt-injected agent could otherwise point this process at a service on the local machine or
+* the network it sits on, and read the answer back through `read_theme_file`.
+*
+* The rules: https only, no credentials in the URL, every address the host resolves to must be
+* public, redirects are followed by hand and each hop checked the same way, and a response is cut
+* off by a deadline and a size cap. The address check runs inside the socket's own DNS lookup, so
+* the address connected to is the address checked; resolving first and connecting afterwards
+* would let a second resolution answer differently.
+*/
+/** Ranges no theme is served from: loopback, private, link-local, shared, reserved, documentation, multicast. */
+var blocked = new BlockList();
+for (const [network, prefix] of [
+	["0.0.0.0", 8],
+	["10.0.0.0", 8],
+	["100.64.0.0", 10],
+	["127.0.0.0", 8],
+	["169.254.0.0", 16],
+	["172.16.0.0", 12],
+	["192.0.0.0", 24],
+	["192.0.2.0", 24],
+	["192.168.0.0", 16],
+	["198.18.0.0", 15],
+	["198.51.100.0", 24],
+	["203.0.113.0", 24],
+	["224.0.0.0", 4],
+	["240.0.0.0", 4]
+]) blocked.addSubnet(network, prefix, "ipv4");
+for (const [network, prefix] of [
+	["::", 128],
+	["::1", 128],
+	["64:ff9b::", 96],
+	["100::", 64],
+	["2001:db8::", 32],
+	["fc00::", 7],
+	["fe80::", 10],
+	["ff00::", 8]
+]) blocked.addSubnet(network, prefix, "ipv6");
+/** Whether an IP address is one on the public internet. Anything that is not an address is not. */
+function isPublicAddress(address) {
+	const family = isIP(address);
+	if (family === 4) return !blocked.check(address, "ipv4");
+	if (family !== 6) return false;
+	const dotted = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(address);
+	if (dotted) return isPublicAddress(dotted[1]);
+	const hex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(address);
+	if (hex) {
+		const [high, low] = [parseInt(hex[1], 16), parseInt(hex[2], 16)];
+		return isPublicAddress(`${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`);
+	}
+	return !blocked.check(address, "ipv6");
+}
+var DEFAULT_TIMEOUT_MS = 15e3;
+/** Far above any real theme file, and a bound on what one response can hold in memory. */
+var DEFAULT_MAX_BYTES = 2 * 1024 * 1024;
+var DEFAULT_MAX_REDIRECTS = 3;
+var NotPublicError = class extends Error {
+	code = "ENOTPUBLIC";
+};
+/** A lookup that answers only when every address the name resolves to is public. */
+function publicOnly(lookup) {
+	return (hostname, options, callback) => {
+		lookup(hostname, { all: true }, (error, addresses) => {
+			if (error) return callback(error);
+			const refused = addresses.find((entry) => !isPublicAddress(entry.address));
+			if (refused || addresses.length === 0) return callback(new NotPublicError(`${hostname} resolves to ${refused?.address ?? "no address"}, which is not a public address.`));
+			if (options.all) callback(null, addresses);
+			else callback(null, addresses[0].address, addresses[0].family);
+		});
+	};
+}
+function checkUrl(url) {
+	if (url.protocol !== "https:") throw new Error(`Only https URLs can be fetched, not ${url.protocol}//${url.host}.`);
+	if (url.username || url.password) throw new Error("A URL with credentials in it cannot be fetched.");
+}
+function fetchOnce(url, deps, deadline) {
+	return new Promise((resolve, reject) => {
+		const remaining = deadline - Date.now();
+		if (remaining <= 0) return reject(/* @__PURE__ */ new Error(`Fetching ${url.href} took longer than ${deps.timeoutMs / 1e3} seconds.`));
+		const req = deps.request(url, {
+			method: "GET",
+			lookup: publicOnly(deps.lookup),
+			headers: {
+				accept: "*/*",
+				"user-agent": "etherpk-mcp"
+			}
+		}, (res) => {
+			const status = res.statusCode ?? 0;
+			if (status >= 300 && status < 400 && res.headers.location) {
+				res.resume();
+				return resolve({ redirect: new URL(res.headers.location, url) });
+			}
+			if (status < 200 || status >= 300) {
+				res.resume();
+				return reject(new Error(`${status} ${res.statusMessage ?? ""}`.trim()));
+			}
+			const chunks = [];
+			let size = 0;
+			res.on("data", (chunk) => {
+				size += chunk.byteLength;
+				if (size > deps.maxBytes) {
+					req.destroy(/* @__PURE__ */ new Error(`${url.href} is larger than ${deps.maxBytes} bytes.`));
+					return;
+				}
+				chunks.push(chunk);
+			});
+			res.on("end", () => {
+				clearTimeout(timer);
+				if (size <= deps.maxBytes) resolve({ text: Buffer.concat(chunks).toString("utf8") });
+			});
+			res.on("error", reject);
+		});
+		const timer = setTimeout(() => req.destroy(/* @__PURE__ */ new Error(`Fetching ${url.href} took longer than ${deps.timeoutMs / 1e3} seconds.`)), remaining);
+		req.on("error", (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+		req.end();
+	});
+}
+/** The text at a public https URL, under the rules at the top of this module. */
+async function fetchPublicText(href, options = {}) {
+	const deps = {
+		lookup: options.lookup ?? lookup,
+		request: options.request ?? request,
+		timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+		maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES,
+		maxRedirects: options.maxRedirects ?? DEFAULT_MAX_REDIRECTS
+	};
+	const deadline = Date.now() + deps.timeoutMs;
+	let url = new URL(href);
+	for (let hops = 0;; hops += 1) {
+		checkUrl(url);
+		const hop = await fetchOnce(url, deps, deadline);
+		if ("text" in hop) return hop.text;
+		if (hops >= deps.maxRedirects) throw new Error(`${href} redirected more than ${deps.maxRedirects} times.`);
+		url = hop.redirect;
+	}
+}
+//#endregion
 //#region src/publish-environment.ts
 /**
 * The publisher's environment in Node (ADR 0082, ADR 0084): themes resolved the way the Client
@@ -15286,11 +16426,8 @@ async function openDiagramRenderer(env) {
 * counterpart of `host/browser-environment.ts`; the core is shared.
 */
 var require = createRequire(import.meta.url);
-async function fetchText$1(url) {
-	const response = await fetch(url);
-	if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
-	return response.text();
-}
+/** A url theme's files, from public https hosts only (see public-fetch.ts). */
+var fetchText$1 = (url) => fetchPublicText(url);
 var katexAssetsPromise = null;
 /** `katex.min.css` plus its woff2 fonts under `fonts/`, as the stylesheet references them. */
 async function katexAssets() {
@@ -15445,6 +16582,56 @@ function withPublishFolder(folders, graphKey, publicationId, folder) {
 	} };
 }
 //#endregion
+//#region src/local-folders.ts
+/**
+* Where the tools may write on this machine. A tool argument is chosen by the agent, and the agent
+* can be steered by what it reads in the notes, so a folder it names is only ever a place under
+* the graph's downloads directory (ADR 0086 keeps even that choice from `publish`). A name that
+* resolves outside it, directly or through a symbolic link, is refused.
+*/
+/** A folder the agent named that is not under the base; the tools report it as `invalid_argument`. */
+var FolderRefused = class extends Error {};
+/** Whether `child` is `parent` or a path beneath it; both already resolved. */
+function within(parent, child) {
+	return child === parent || child.startsWith(parent.endsWith(sep) ? parent : parent + sep);
+}
+/** The nearest part of `path` that exists on disk: the path itself, or its closest existing parent. */
+async function existingPart(path) {
+	let at = path;
+	for (;;) try {
+		await lstat(at);
+		return at;
+	} catch {
+		const up = dirname(at);
+		if (up === at) return at;
+		at = up;
+	}
+}
+/**
+* The folder the agent asked for under `base`, or `fallback` (a path relative to `base`) when it
+* named none. A relative name is taken relative to `base`; an absolute one must already be under
+* it. Checked twice: as written, and after resolving every symbolic link in the part that exists.
+*/
+async function folderUnder(base, requested, fallback) {
+	const root = resolve(base);
+	const wanted = requested?.trim() ? requested.trim() : fallback;
+	const target = resolve(root, wanted);
+	if (!within(root, target)) throw new FolderRefused(`"${wanted}" is outside ${root}. Name a folder under it, or leave it out for the default.`);
+	await mkdir(root, { recursive: true });
+	if (!within(await realpath(root), await realpath(await existingPart(target)))) throw new FolderRefused(`"${wanted}" leads outside ${root} through a symbolic link.`);
+	return target;
+}
+/**
+* Whether a preview page may load `url`: its own files and inline data, nothing else. A theme's
+* script runs when the preview is photographed, and a theme can come from a collaborator or a URL,
+* so the page is kept off the network and away from the rest of the disk.
+*/
+function previewRequestAllowed(url, folder) {
+	if (url.startsWith("data:") || url.startsWith("blob:") || url === "about:blank") return true;
+	const own = pathToFileURL(folder.endsWith(sep) ? folder : folder + sep).href;
+	return url.startsWith(own);
+}
+//#endregion
 //#region src/headless-assets.ts
 /**
 * What the asset tools need from a graph's [[Asset]]s, behind one seam for both backends
@@ -15455,9 +16642,46 @@ function withPublishFolder(folders, graphKey, publicationId, folder) {
 * reference names an asset (`identify`), which is what the index is asked about when the tools
 * decide whether an asset is reachable from a document the agent can read.
 */
-/** A local file as `upload_asset` reads it. */
-async function readLocalFile(path) {
-	const buffer = await readFile(path);
+/**
+* The largest file `upload_asset` reads. The Sync Server applies its own, usually smaller, limit;
+* this one bounds what a single call can pull into memory whatever the backend.
+*/
+var MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
+async function realOrResolved(path) {
+	try {
+		return await realpath(path);
+	} catch {
+		return resolve(path);
+	}
+}
+/**
+* Refuse a file an agent should not be able to put into a graph. The path is a tool argument, and
+* an agent can be steered by what it reads, so an upload is a way to copy a local file somewhere
+* collaborators can read it. Refused: the Headless Client's cache (the graph's decrypted
+* contents) and config (sign-in tokens), and anything hidden (a dot-file, or a file inside a
+* dot-folder such as `.ssh` or `.aws`), which is where credentials and settings live. `real` has
+* every link resolved, so a link is judged by the file it leads to.
+*/
+async function refuseProtected(path, real, rules) {
+	if (within(await realOrResolved(rules.downloadsDir), real)) return;
+	if (within(await realOrResolved(cacheRoot(rules.env)), real)) throw new Error(`${path} is in the Headless Client's cache, which holds the graph's decrypted contents.`);
+	const configFile = await realOrResolved(defaultConfigPath(rules.env));
+	const configDir = await realOrResolved(dirname(defaultConfigPath({
+		...rules.env,
+		ETHERPK_MCP_CONFIG: void 0
+	})));
+	if (real === configFile || within(configDir, real)) throw new Error(`${path} is the Headless Client's config, which holds its sign-in tokens.`);
+	const hidden = real.split(sep).find((part) => part.startsWith("."));
+	if (hidden) throw new Error(`${path} is hidden (${hidden}), where credentials and settings are kept. Copy it to an ordinary folder to upload it.`);
+}
+/** A local file as `upload_asset` reads it: an ordinary file, not refused above, within the size limit. */
+async function readLocalFile(path, rules) {
+	const real = await realpath(path);
+	await refuseProtected(path, real, rules);
+	const info = await stat(real);
+	if (!info.isFile()) throw new Error(`${path} is not a file.`);
+	if (info.size > 104857600) throw new Error(`${path} is larger than ${MAX_UPLOAD_BYTES / (1024 * 1024)} MiB.`);
+	const buffer = await readFile(real);
 	const bytes = new Uint8Array(new ArrayBuffer(buffer.byteLength));
 	bytes.set(buffer);
 	return {
@@ -15465,24 +16689,54 @@ async function readLocalFile(path) {
 		bytes
 	};
 }
-/**
-* Write an asset's bytes under `directory` as `name`, never over a different file of the same
-* name: a second asset that happens to share a display name lands beside it with a suffix, so
-* an agent reading two `diagram.png`s from two pages gets both.
+/** Names Windows reserves for devices, whatever the extension. */
+var RESERVED = /^(con|prn|aux|nul|com\d|lpt\d)$/i;
+var MAX_NAME_LENGTH = 120;
+/**
+* A file name for an asset's stored name. The stored name is metadata any collaborator can set,
+* so it is reduced to one plain file: the last path segment, letters, digits, marks, spaces and
+* `. _ - ( )` kept and everything else replaced, no leading dot (so never hidden, never `..`),
+* no trailing dot or space (Windows drops them), not a Windows device name, and short.
+*/
+function downloadName(name) {
+	let safe = (name.split(/[\\/]/).pop() ?? "").replace(/[^\p{L}\p{M}\p{N} ._()-]/gu, "_").replace(/^[.\s]+/, "").replace(/[.\s]+$/, "");
+	if (safe === "") return "asset";
+	if (RESERVED.test(safe.split(".")[0])) safe = `_${safe}`;
+	if (Array.from(safe).length <= MAX_NAME_LENGTH) return safe;
+	const dot = safe.lastIndexOf(".");
+	const ext = dot > 0 && safe.length - dot <= 20 ? safe.slice(dot) : "";
+	return Array.from(safe.slice(0, safe.length - ext.length)).slice(0, MAX_NAME_LENGTH - ext.length).join("") + ext;
+}
+/** Whether `path` is an ordinary file (not a link) holding exactly `bytes`. */
+async function holds(path, bytes) {
+	const info = await lstat(path);
+	if (!info.isFile() || info.size !== bytes.byteLength) return false;
+	return (await readFile(path)).equals(bytes);
+}
+/**
+* Write an asset's bytes under `directory`, named by {@link downloadName}, and never over
+* anything already there: the write fails rather than replace a file or follow a link left in
+* its place, and the next candidate is tried. A second asset that shares a display name lands
+* beside the first with a suffix, so an agent reading two `diagram.png`s from two pages gets
+* both; the same bytes again answer the file already written.
 */
 async function writeDownload(directory, name, bytes) {
 	await mkdir(directory, { recursive: true });
-	const dot = name.lastIndexOf(".");
-	const stem = dot > 0 ? name.slice(0, dot) : name;
-	const ext = dot > 0 ? name.slice(dot) : "";
-	let candidate = join(directory, name);
-	for (let n = 2; existsSync(candidate); n += 1) {
-		const existing = await readFile(candidate);
-		if (existing.byteLength === bytes.byteLength && existing.every((b, i) => b === bytes[i])) return candidate;
-		candidate = join(directory, `${stem}-${n}${ext}`);
-	}
-	await writeFile(candidate, bytes);
-	return candidate;
+	const safe = downloadName(name);
+	const dot = safe.lastIndexOf(".");
+	const stem = dot > 0 ? safe.slice(0, dot) : safe;
+	const ext = dot > 0 ? safe.slice(dot) : "";
+	for (let n = 1; n <= 1e3; n += 1) {
+		const candidate = join(directory, n === 1 ? safe : `${stem}-${n}${ext}`);
+		try {
+			await writeFile(candidate, bytes, { flag: "wx" });
+			return candidate;
+		} catch (error) {
+			if (error.code !== "EEXIST") throw error;
+		}
+		if (await holds(candidate, bytes)) return candidate;
+	}
+	throw new Error(`${directory} already holds a thousand files named like ${safe}.`);
 }
 /** UTF-16 units of document text returned before `truncated` is set. */
 var READ_TEXT_CAP = 2e5;
@@ -15604,7 +16858,7 @@ function bounded(value, fallback, max) {
 */
 async function settle$2(graph) {
 	const result = await graph.settle();
-	if (!result.settled) throw new ToolError("not_settled", result.message);
+	if (!result.settled) throw new ToolError(result.code ?? "not_settled", result.message);
 }
 async function listDocuments(graph, args = {}) {
 	await graph.store.refresh();
@@ -15844,7 +17098,7 @@ async function setFrontmatter(graph, args) {
 	const body = await liveText(graph, identity);
 	refuseIfProtected(identity.concept, body);
 	const raw = graph.store.openRaw(identity.concept).getText();
-	const next = patchedText(raw, args.patch);
+	const next = withAliasesInAddedBlock(raw, patchedText(raw, args.patch), identity.aliases);
 	applyBlock(graph, identity.concept, raw, next);
 	await settle$2(graph);
 	return {
@@ -16029,7 +17283,10 @@ async function uploadAsset(graph, args) {
 	if (!args.path || args.path.trim() === "") throw new ToolError("invalid_argument", "path must name a file on this machine.");
 	let file;
 	try {
-		file = await readLocalFile(args.path.trim());
+		file = await readLocalFile(args.path.trim(), {
+			env: process.env,
+			downloadsDir: assets.downloadsDir
+		});
 	} catch (error) {
 		throw new ToolError("invalid_argument", `Cannot read "${args.path}": ${error instanceof Error ? error.message : String(error)}`);
 	}
@@ -16074,8 +17331,15 @@ async function readAsset(graph, args) {
 	if (!documents) throw new ToolError("asset_not_found", `No document you can read references "${displayNameOf(ref)}", so it is not available here.`);
 	const asset = await assets.store.readBytes(ref);
 	if (!asset) throw new ToolError("asset_not_found", `The graph does not hold "${displayNameOf(ref)}" (the reference may be broken).`);
+	let directory;
+	try {
+		directory = await folderUnder(assets.downloadsDir, args.out_dir, ".");
+	} catch (error) {
+		if (error instanceof FolderRefused) throw new ToolError("invalid_argument", error.message);
+		throw error;
+	}
 	return {
-		path: await writeDownload(args.out_dir?.trim() || assets.downloadsDir, asset.name || displayNameOf(ref), asset.bytes),
+		path: await writeDownload(directory, asset.name || displayNameOf(ref), asset.bytes),
 		name: asset.name || displayNameOf(ref),
 		type: asset.type,
 		bytes: asset.bytes.byteLength,
@@ -16308,9 +17572,30 @@ async function graphInfo(graph) {
 function hostOf$1(host) {
 	return {
 		env: host?.env ?? process.env,
-		cmd: host?.cmd ?? "etherpk-mcp"
+		cmd: host?.cmd ?? "etherpk-mcp",
+		via: host?.via ?? "agent"
 	};
 }
+/**
+* The refusal for an id no publication has, naming the ids there are. An agent is pointed at
+* its tool; a person at the command line, who has no agent tool to run, at the Publish tab.
+*/
+function publicationNotFound(id, publications, via) {
+	const where = via === "cli" ? "Settings → Publish in EtherPK lists them." : "list_publications shows them.";
+	return new ToolError("publication_not_found", `No publication has the id "${id}". ${publications.length === 0 ? "This graph defines no publication yet." : `Its publications: ${publications.map((p) => p.id).join(", ")}.`} ${where}`);
+}
+/**
+* The publication with this id, or the refusal a publish would give. The command line asks
+* before it remembers a publish folder, so a mistyped id is not written down.
+*/
+async function findPublication(graph, id, host) {
+	const { via } = hostOf$1(host);
+	await graph.store.refresh();
+	const { publications } = summarisePublishing((await graph.publishing.readSource()).source);
+	const found = publications.find((p) => p.id === id.trim());
+	if (!found) throw publicationNotFound(id, publications, via);
+	return found;
+}
 /** The publication page's mapping and body, through the raw handles: what `publish-service` writes to. */
 function frontmatterStore(graph) {
 	return {
@@ -16411,8 +17696,9 @@ async function createPublication(graph, args, host) {
 async function updatePublication(graph, args, host) {
 	const { env } = hostOf$1(host);
 	await graph.store.refresh();
-	const current = summarisePublishing((await graph.publishing.readSource()).source).publications.find((p) => p.id === args.id.trim());
-	if (!current) throw new ToolError("publication_not_found", `No publication has the id "${args.id}"; list_publications shows them.`);
+	const all = summarisePublishing((await graph.publishing.readSource()).source).publications;
+	const current = all.find((p) => p.id === args.id.trim());
+	if (!current) throw publicationNotFound(args.id, all, hostOf$1(host).via);
 	const changes = args.changes ?? {};
 	if (changes.kind !== void 0 && changes.kind !== null && changes.kind !== "docs" && changes.kind !== "blog") throw new ToolError("invalid_argument", "kind must be \"docs\" or \"blog\".");
 	if (changes.selection !== void 0 && changes.selection !== null && changes.selection !== "named" && changes.selection !== "all-public") throw new ToolError("invalid_argument", "selection must be \"named\" or \"all-public\".");
@@ -16425,6 +17711,12 @@ async function updatePublication(graph, args, host) {
 	const folderOf = await foldersFor(graph, env);
 	return { publication: publicationView(after ?? current, folderOf(current.id)) };
 }
+/** How many items fall under each key. */
+function countBy(items, keyOf) {
+	const counts = {};
+	for (const item of items) counts[keyOf(item)] = (counts[keyOf(item)] ?? 0) + 1;
+	return counts;
+}
 /** The first entries of a long list, and how many there were. */
 function head(items, n = 20) {
 	return {
@@ -16435,15 +17727,22 @@ function head(items, n = 20) {
 /**
 * Publish one publication into its Publish Folder and report. The folder is the one a person
 * set for this graph and publication on this machine (ADR 0086); a publish with Mermaid needs
-* the browser (ADR 0084). The full report is in the folder as `etherpk-publish.json`.
+* the browser (ADR 0084).
+*
+* The result IS the report, trimmed to counts and first entries: nothing of it is written into
+* the folder, because a static host serves whatever the folder holds and the report names every
+* document the site leaves out, protected ones included. The documents left out are counted by
+* reason rather than listed: that is every document outside the publication, most of a large
+* graph. The command line prints {@link cliPublishOutput} instead, which names nothing the site
+* leaves out.
 */
 async function publish(graph, args, host) {
-	const { env, cmd } = hostOf$1(host);
+	const { env, cmd, via } = hostOf$1(host);
 	await graph.store.refresh();
 	const { source, unsettled } = await graph.publishing.readSource();
 	const summary = summarisePublishing(source);
 	const publication = summary.publications.find((p) => p.id === args.id.trim());
-	if (!publication) throw new ToolError("publication_not_found", `No publication has the id "${args.id}"; list_publications shows them.`);
+	if (!publication) throw publicationNotFound(args.id, summary.publications, via);
 	const folder = (await foldersFor(graph, env))(publication.id);
 	if (!folder) {
 		const where = graph.backend.kind === "folder" ? `--folder "${graph.backend.path}"` : `--graph "${graph.name}"`;
@@ -16490,20 +17789,47 @@ async function publish(graph, args, host) {
 			},
 			errors: run.report.errors,
 			warnings: run.report.warnings,
-			missingLinks: head(run.report.missingLinks),
+			missingLinks: {
+				...head(run.report.missingLinks),
+				byStatus: countBy(run.report.missingLinks, (link) => link.status)
+			},
 			assets: {
 				copied: run.report.assets.copied.length,
 				missing: run.report.assets.missing
 			},
 			collisions: run.report.collisions,
 			publicInNoPublication: run.report.publicInNoPublication,
-			...unsettled.length > 0 ? { unsettled } : {},
-			report: run.report.ok ? `${folder}/etherpk-publish.json` : null
+			...unsettled.length > 0 ? { unsettled } : {}
 		};
 	} finally {
 		await renderer?.dispose();
 	}
 }
+/**
+* What `etherpk-mcp publish` prints: the tool's result with every name the site leaves out
+* reduced to a count. A scheduled publish's log can be as public as the site (a public CI run),
+* so links are counted by status (a "private" status says a hidden page exists), documents not
+* yet synced and public documents in no publication are counted, and warnings keep their codes
+* without the sentences that name pages. What was published, and the errors that stopped a
+* publish, are printed as they are: the site shows the one, and the other is what to fix.
+*/
+function cliPublishOutput(result) {
+	const { unsettled, ...rest } = result;
+	return {
+		...rest,
+		missingLinks: {
+			total: result.missingLinks.total,
+			byStatus: result.missingLinks.byStatus
+		},
+		warnings: {
+			total: result.warnings.length,
+			byCode: countBy(result.warnings, (warning) => warning.code)
+		},
+		publicInNoPublication: result.publicInNoPublication.length,
+		...unsettled ? { unsettled: unsettled.length } : {},
+		note: "Documents the site leaves out are counted here, not named. Settings → Publish in EtherPK shows the full report."
+	};
+}
 /** The publishing half of `graph_info`: each publication with its folder here, and whether diagrams can be drawn. */
 async function publishingInfo(graph, host) {
 	const { env, cmd } = hostOf$1(host);
@@ -16626,15 +17952,25 @@ function hostOf(host) {
 		cmd: host?.cmd ?? "etherpk-mcp"
 	};
 }
+/** The graph's downloads directory: every folder these tools write to, or read a theme back from, is under it. */
+function downloadsOf(graph) {
+	return graph.assets?.downloadsDir ?? join(process.cwd(), "etherpk-downloads");
+}
+/** A folder under the downloads directory, or the tool's refusal. */
+async function toolFolder(graph, requested, fallback) {
+	try {
+		return await folderUnder(downloadsOf(graph), requested, fallback);
+	} catch (error) {
+		if (error instanceof FolderRefused) throw new ToolError("invalid_argument", error.message);
+		throw error;
+	}
+}
 async function settle(graph) {
 	const result = await graph.settle();
 	if (!result.settled) throw new ToolError("not_settled", result.message);
 }
-async function fetchText(url) {
-	const response = await fetch(url);
-	if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
-	return response.text();
-}
+/** A url theme's files, from public https hosts only (see public-fetch.ts). */
+var fetchText = (url) => fetchPublicText(url);
 /** The publications whose saved mapping names a theme: what makes it undeletable. */
 async function publicationsUsing(graph, themeId) {
 	const { source } = await graph.publishing.readSource();
@@ -16731,12 +18067,11 @@ async function readTheme(graph, args) {
 	await graph.store.refresh();
 	const ref = args.ref.trim();
 	const { source, files, theme } = await filesOf(graph, ref);
-	const folder = resolve(args.out_dir?.trim() || join(graph.assets?.downloadsDir ?? join(process.cwd(), "etherpk-downloads"), "themes", ref.replace(/[^A-Za-z0-9._-]/g, "_")));
+	const folder = await toolFolder(graph, args.out_dir, join("themes", ref.replace(/[^A-Za-z0-9._-]/g, "_")));
+	const site = nodeSiteFolder(folder);
 	const written = [];
 	for (const [path, text] of [...files.entries()].sort(([a], [b]) => a.localeCompare(b))) {
-		const full = join(folder, ...path.split("/"));
-		await mkdir(dirname(full), { recursive: true });
-		await writeFile(full, text);
+		await site.writeFile(path, text);
 		written.push({
 			path,
 			bytes: Buffer.byteLength(text)
@@ -16888,22 +18223,43 @@ async function deleteThemeFile(graph, args) {
 		errors: validationOf(after)
 	};
 }
-/** Every allowed file under a directory, as the theme's whole file set. */
-async function filesUnder(dir) {
-	const base = resolve(dir);
+/** Bounds on a theme folder: far beyond a real theme, and short of a whole disk. */
+var THEME_FOLDER_LIMITS = {
+	files: 500,
+	depth: 6,
+	fileBytes: 1024 * 1024,
+	totalBytes: 8 * 1024 * 1024
+};
+/**
+* Every allowed file under a directory, as the theme's whole file set. Symbolic links are not
+* followed, so a folder cannot pull in a file from elsewhere on disk, and the walk stops at the
+* limits above rather than reading whatever tree it was pointed at.
+*/
+async function filesUnder(base) {
 	const files = /* @__PURE__ */ new Map();
-	const walk = async (at) => {
+	let seen = 0;
+	let total = 0;
+	const walk = async (at, depth) => {
+		if (depth > THEME_FOLDER_LIMITS.depth) return;
 		for (const entry of await readdir(at, { withFileTypes: true })) {
+			if (entry.isSymbolicLink()) continue;
 			const full = join(at, entry.name);
 			if (entry.isDirectory()) {
-				if (entry.name !== ".git" && entry.name !== "node_modules") await walk(full);
+				if (entry.name !== ".git" && entry.name !== "node_modules") await walk(full, depth + 1);
 				continue;
 			}
+			if (!entry.isFile()) continue;
+			if (++seen > THEME_FOLDER_LIMITS.files) throw new Error(`it holds more than ${THEME_FOLDER_LIMITS.files} files`);
 			const path = relative(base, full).split(sep).join("/");
-			if (isThemeFilePath(path)) files.set(path, await readFile(full, "utf8"));
+			if (!isThemeFilePath(path)) continue;
+			const { size } = await lstat(full);
+			if (size > THEME_FOLDER_LIMITS.fileBytes) throw new Error(`${path} is larger than ${THEME_FOLDER_LIMITS.fileBytes} bytes`);
+			total += size;
+			if (total > THEME_FOLDER_LIMITS.totalBytes) throw new Error(`its theme files come to more than ${THEME_FOLDER_LIMITS.totalBytes} bytes`);
+			files.set(path, await readFile(full, "utf8"));
 		}
 	};
-	await walk(base);
+	await walk(base, 0);
 	return files;
 }
 /**
@@ -16914,9 +18270,11 @@ async function filesUnder(dir) {
 async function importThemeFolder(graph, args) {
 	await graph.store.refresh();
 	const theme = await requireEditable(graph, args.id.trim());
+	if (!args.dir?.trim()) throw new ToolError("invalid_argument", "dir must name the theme folder, as read_theme returned it.");
+	const dir = await toolFolder(graph, args.dir, "");
 	let files;
 	try {
-		files = await filesUnder(args.dir);
+		files = await filesUnder(dir);
 	} catch (error) {
 		throw new ToolError("invalid_argument", `Cannot read "${args.dir}": ${error instanceof Error ? error.message : String(error)}`);
 	}
@@ -16953,8 +18311,8 @@ async function deleteTheme(graph, args) {
 /**
 * Render a theme to a folder on this machine and say where: the publication's real site when
 * one is named, the sample site the Theme editor previews over otherwise. A preview is scratch,
-* not a [[Publish Folder]]: the default location is under the graph's downloads directory and is
-* emptied first; a named `out_dir` is written into as it is. With `screenshots`, the browser
+* not a [[Publish Folder]]: it is always under the graph's downloads directory, the default folder
+* there is emptied first, and a named `out_dir` (also under it) is written into as it is. With `screenshots`, the browser
 * photographs the front page and the first other page at desktop and phone widths, so the agent
 * can look at what it changed.
 */
@@ -16987,7 +18345,7 @@ async function previewTheme(graph, args, host) {
 		});
 		const { bundle, report } = await publishPublication(source, publication, environment);
 		const scratch = !args.out_dir?.trim();
-		const folder = resolve(args.out_dir?.trim() || join(graph.assets?.downloadsDir ?? join(process.cwd(), "etherpk-downloads"), "previews", themeRef.replace(/[^A-Za-z0-9._-]/g, "_")));
+		const folder = await toolFolder(graph, args.out_dir, join("previews", themeRef.replace(/[^A-Za-z0-9._-]/g, "_")));
 		if (scratch) await rm(folder, {
 			recursive: true,
 			force: true
@@ -17018,12 +18376,10 @@ async function previewTheme(graph, args, host) {
 		await renderer?.dispose();
 	}
 }
+/** The rendered site into the folder, through the writer `publish` uses: no path may leave the folder. */
 async function writeBundle(folder, bundle) {
-	for (const [path, content] of bundle) {
-		const full = join(folder, ...path.split("/"));
-		await mkdir(dirname(full), { recursive: true });
-		await writeFile(full, content);
-	}
+	const site = nodeSiteFolder(folder);
+	for (const [path, content] of bundle) await site.writeFile(path, content);
 }
 /** The front page and the first other page, desktop and phone, as PNGs beside the site. */
 async function photograph(env, folder, pages) {
@@ -17033,12 +18389,16 @@ async function photograph(env, folder, pages) {
 		const shots = [];
 		const targets = ["index.html", ...pages.filter((p) => p !== "index.html" && p !== "404.html").slice(0, 1)];
 		for (const page of targets) for (const width of [1280, 390]) {
-			const context = await browser.newContext({ viewport: {
-				width,
-				height: width === 390 ? 844 : 800
-			} });
+			const context = await browser.newContext({
+				viewport: {
+					width,
+					height: width === 390 ? 844 : 800
+				},
+				offline: true
+			});
+			await context.route("**/*", (route) => previewRequestAllowed(route.request().url(), folder) ? route.continue() : route.abort());
 			const tab = await context.newPage();
-			await tab.goto(`file://${join(folder, page)}`, { waitUntil: "load" });
+			await tab.goto(pathToFileURL(join(folder, page)).href, { waitUntil: "load" });
 			const out = join(folder, `preview-${page.replace(/\.html$/, "")}-${width}.png`);
 			await tab.screenshot({
 				path: out,
@@ -17085,13 +18445,22 @@ function failed(error) {
 		isError: true
 	};
 }
-async function run(work) {
+async function runTool(work) {
 	try {
 		return ok(await work());
 	} catch (error) {
 		return failed(error);
 	}
 }
+/**
+* The refusal every tool gives once the Sync Server has ended access, instead of answering from
+* a cache that can no longer be trusted or saved.
+*/
+function accessEndedError(graph, cmd) {
+	const loss = graph.accessLoss();
+	if (!loss) return null;
+	return loss.kind === "membership" ? new ToolError("access_removed", `This account no longer has access to the graph: it left, was removed by the owner, or the graph was deleted. Run ${cmd} graphs to see the graphs it can reach.`) : new ToolError("token_revoked", `The Sync Server no longer accepts this computer's access token: it was revoked or has expired, or the account's password was reset. Run ${cmd} login again.`);
+}
 var concept = z.string().min(1).describe("A page title, one of its aliases, a journal day as YYYY-MM-DD, or \"today\".");
 var offset = z.number().int().nonnegative().optional().describe("Skip this many results (paging).");
 /** A frontmatter value as JSON carries it; the writer turns it into YAML. */
@@ -17104,6 +18473,11 @@ var frontmatterValue = z.union([
 	z.record(z.string(), z.unknown())
 ]);
 function createMcpServer(graph, info) {
+	const run = (work) => runTool(() => {
+		const ended = accessEndedError(graph, info.cmd ?? "etherpk-mcp");
+		if (ended) throw ended;
+		return work();
+	});
 	const server = new McpServer({
 		name: "etherpk",
 		version: info.version
@@ -17118,7 +18492,7 @@ function createMcpServer(graph, info) {
 		"Start with graph_info to see what you are connected to. read_documents reads several documents in one call; tasks lists tasks and set_task changes one (status, priority, due and scheduled dates) by document and line.",
 		"Publishing: list_publications shows the publications this graph defines (a publication is a page whose frontmatter defines it; its outline is the site navigation) and the public documents none takes; a document is on a site when its frontmatter has public: true and names the publication in publications. create_publication and update_publication change the settings; publish writes the site into the publish folder the user set for it on this machine with the etherpk-mcp publish command (the tool cannot choose a folder) and returns the report. Diagrams need a browser the user installs once with \"diagrams setup\".",
 		"Themes: a publication's look is a theme - Mustache templates, a stylesheet, a script and a manifest. list_themes shows the bundled ones (read-only) and the graph's own; read_theme writes a theme's files to a folder on this machine to read and edit; customise_publication_theme copies a publication's bundled theme into the graph and points the publication at the copy (create_theme copies any theme); write_theme_file, delete_theme_file and import_theme_folder change a graph theme; preview_theme renders a theme to a folder (with screenshots when a browser is set up) to check before publish. For a snippet such as an analytics script, an include slot (update_publication includes, e.g. head) filled by a page may be lighter than a theme copy.",
-		"Images and files are assets: upload_asset adds a file from this machine and returns the markdown to paste into a document; read_asset writes an asset to a local file you can open; list_assets shows the assets documents reference. An asset is available only where a document you can read references it (or you uploaded it this session).",
+		"Images and files are assets: upload_asset adds a file from this machine and returns the markdown to paste into a document; read_asset writes an asset to a local file you can open; list_assets shows the assets documents reference. An asset is available only where a document you can read references it (or you uploaded it this session). read_asset, read_theme and preview_theme write under the graph's downloads directory and return the path; name a folder relative to it, never elsewhere.",
 		"The user documentation is at https://docs.etherpk.com."
 	].join("\n") });
 	server.registerTool("list_documents", {
@@ -17277,18 +18651,18 @@ function createMcpServer(graph, info) {
 	}, async (args) => run(() => setFrontmatter(graph, args)));
 	server.registerTool("upload_asset", {
 		title: "Upload an asset",
-		description: "Add a file on this machine (an image, a PDF, any file) to the graph as an asset. Returns the reference and the markdown to paste into a document (an image tag for an image, a link otherwise). Bytes the graph already holds are not stored twice: the result then says reused: true and points at the existing asset. The file is stored as it is, without image optimisation. Refused with error \"asset_refused\" when the server declines it on a quota.",
+		description: "Add a file on this machine (an image, a PDF, any file) to the graph as an asset. Returns the reference and the markdown to paste into a document (an image tag for an image, a link otherwise). Bytes the graph already holds are not stored twice: the result then says reused: true and points at the existing asset. The file is stored as it is, without image optimisation. Refused with error \"invalid_argument\" for a folder, a file over 100 MiB, a hidden file or one in a hidden folder (.ssh, .env), and the Headless Client's own config and cache; with error \"asset_refused\" when the server declines it on a quota.",
 		inputSchema: {
-			path: z.string().min(1).describe("Absolute path of the file on this machine."),
+			path: z.string().min(1).describe("Absolute path of an ordinary file on this machine."),
 			name: z.string().min(1).optional().describe("The name to store it under; the file's own name by default.")
 		}
 	}, async (args) => run(() => uploadAsset(graph, args)));
 	server.registerTool("read_asset", {
 		title: "Read an asset",
-		description: "Write an asset's bytes to a file on this machine and return the path, so you can open or view it. Pass the reference as a document shows it (\"../assets/<name>\") or the name alone. Available only where a document you can read references the asset (or you uploaded it this session); otherwise error \"asset_not_found\".",
+		description: "Write an asset's bytes to a file on this machine and return the path, so you can open or view it. Pass the reference as a document shows it (\"../assets/<name>\") or the name alone. Available only where a document you can read references the asset (or you uploaded it this session); otherwise error \"asset_not_found\". The file is written under the graph's downloads directory, named after the asset, and never over an existing file.",
 		inputSchema: {
 			ref: z.string().min(1),
-			out_dir: z.string().min(1).optional().describe("Directory to write into; the graph's downloads directory by default.")
+			out_dir: z.string().min(1).optional().describe("A folder under the graph's downloads directory, relative to it; the downloads directory itself by default. A folder outside it is refused.")
 		}
 	}, async (args) => run(() => readAsset(graph, args)));
 	server.registerTool("list_assets", {
@@ -17336,7 +18710,7 @@ function createMcpServer(graph, info) {
 	}, async (args) => run(() => updatePublication(graph, args, host)));
 	server.registerTool("publish", {
 		title: "Publish",
-		description: "Render a publication to its publish folder on this machine and return the report: what was included and why documents were left out, missing links, assets, warnings. The folder is the one the user set with \"etherpk-mcp publish --publication <id> --out <dir>\" (error \"no_publish_folder\" until then; the tool never chooses a folder). Pages with Mermaid diagrams need the browser from \"diagrams setup\" (error \"chromium_unavailable\"). The full report is written to the folder as etherpk-publish.json. Publishing writes files; it does not deploy them.",
+		description: "Render a publication to its publish folder on this machine and return the report: what was included and why documents were left out, missing links, assets, warnings. The folder is the one the user set with \"etherpk-mcp publish --publication <id> --out <dir>\" (error \"no_publish_folder\" until then; the tool never chooses a folder). Pages with Mermaid diagrams need the browser from \"diagrams setup\" (error \"chromium_unavailable\"). The report is this result, trimmed to counts and first entries; nothing of it is written into the folder, so the site never names the documents it leaves out. Publishing writes files; it does not deploy them.",
 		inputSchema: { id: z.string().min(1) }
 	}, async (args) => run(() => publish(graph, args, host)));
 	server.registerTool("list_themes", {
@@ -17349,7 +18723,7 @@ function createMcpServer(graph, info) {
 		description: "Write a theme's files (theme.json, layouts/, partials/, assets/) to a folder on this machine and return the path and file list, so you can read and edit them with your own tools. ref is a graph theme id, a bundled theme name or a url. Editing the folder changes nothing until write_theme_file or import_theme_folder brings it back; a bundled or url theme cannot be edited in place at all (create_theme copies it).",
 		inputSchema: {
 			ref: z.string().min(1),
-			out_dir: z.string().min(1).optional().describe("Directory to write into; the graph's downloads directory by default.")
+			out_dir: z.string().min(1).optional().describe("A folder under the graph's downloads directory, relative to it; themes/<ref> there by default. A folder outside it is refused.")
 		}
 	}, async (args) => run(() => readTheme(graph, args)));
 	server.registerTool("read_theme_file", {
@@ -17397,7 +18771,7 @@ function createMcpServer(graph, info) {
 	}, async (args) => run(() => deleteThemeFile(graph, args)));
 	server.registerTool("import_theme_folder", {
 		title: "Import a theme folder",
-		description: "Replace a graph theme's files with a folder's contents - the way back after editing what read_theme wrote. Files the folder no longer has are removed from the theme; the folder needs a theme.json at its top. Validated afterwards.",
+		description: "Replace a graph theme's files with a folder's contents - the way back after editing what read_theme wrote. Files the folder no longer has are removed from the theme; the folder needs a theme.json at its top. dir is the folder read_theme returned, or another under the graph's downloads directory; a folder outside it is refused, and symbolic links in it are skipped. Validated afterwards.",
 		inputSchema: {
 			id: z.string().min(1),
 			dir: z.string().min(1)
@@ -17410,7 +18784,7 @@ function createMcpServer(graph, info) {
 	}, async (args) => run(() => deleteTheme(graph, args)));
 	server.registerTool("preview_theme", {
 		title: "Preview a theme",
-		description: "Render a theme to a folder on this machine and return where: a publication's real pages when a publication is given (with its own theme, or the theme named), or a sample site covering every construct when only a theme is given. Open the HTML to check markup and styles. With screenshots: true and a browser set up (diagrams setup or ETHERPK_CHROMIUM), the front page and one content page are photographed at desktop and phone widths as PNGs you can view. A preview is scratch, not the publish folder.",
+		description: "Render a theme to a folder on this machine and return where: a publication's real pages when a publication is given (with its own theme, or the theme named), or a sample site covering every construct when only a theme is given. Open the HTML to check markup and styles. With screenshots: true and a browser set up (diagrams setup or ETHERPK_CHROMIUM), the front page and one content page are photographed at desktop and phone widths as PNGs you can view. A preview is scratch, not the publish folder. The page loads nothing from the network while it is photographed. out_dir is a folder under the graph's downloads directory (previews/<name> there by default); a folder outside it is refused.",
 		inputSchema: {
 			theme: z.string().min(1).optional(),
 			publication: z.string().min(1).optional(),
@@ -17460,9 +18834,18 @@ function standalone(bytes) {
 	copy.set(bytes);
 	return copy;
 }
+/**
+* `name` as one file of `folder`, or a refusal. The store passes names that came from documents
+* (an asset reference decodes to one), and `join` would follow a `..` or a separator out of the
+* graph; the browser's directory handles refuse such names, and this keeps the two adapters alike.
+*/
+function fileIn(folder, name) {
+	if (!isSingleFileName(name)) throw new Error(`"${name}" is not a file name.`);
+	return join(folder, name);
+}
 function createNodeDirectoryAdapter(root) {
 	const dir = resolve(root);
-	const path = (subdir, name) => join(dir, subdir, name);
+	const path = (subdir, name) => fileIn(join(dir, subdir), name);
 	/**
 	* The file's mtime as integer milliseconds, as the browser's `File.lastModified` is. Node's
 	* `mtimeMs` is a float built from seconds plus nanoseconds, and on some filesystems the
@@ -17543,7 +18926,7 @@ function createNodeDirectoryAdapter(root) {
 			for (const subdir of SUBDIRS) await mkdir(join(dir, subdir), { recursive: true });
 		},
 		async readRootFile(name) {
-			const file = join(dir, name);
+			const file = fileIn(dir, name);
 			let text;
 			try {
 				text = await readFile(file, "utf8");
@@ -17557,7 +18940,7 @@ function createNodeDirectoryAdapter(root) {
 			};
 		},
 		async writeRootFile(name, text) {
-			const file = join(dir, name);
+			const file = fileIn(dir, name);
 			await writeFile(file, text, "utf8");
 			return {
 				text,
@@ -17609,7 +18992,7 @@ function bindServeLifetime(deps) {
 *   etherpk-mcp diagrams setup | status
 *
 * One config file holds a login per Sync Server (ADR 0075). `--sync-server` names the one a
-* command means and may be left out while only one is signed in.
+* command means and may be left out while there is only one login.
 *
 * `serve` speaks MCP over stdio, so everything for the human goes to stderr; stdout belongs
 * to the agent. `login` and `graphs` are interactive and print to stdout.
@@ -17628,11 +19011,11 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
       Sign this machine in as a device of your account. Prompts for a Personal Access
       Token (an account-wide one, from the Sync Server portal at <url>/account/tokens)
       unless --pat or ETHERPK_PAT is given, then unlocks your keys by Device Approval:
-      open EtherPK in a browser signed in to the account with its graphs unlocked and
+      open EtherPK in a browser connected to the account with its keys unlocked and
       confirm the code shown. Press r while waiting, or pass --recovery-code, to type
       your Recovery Code instead (or ETHERPK_RECOVERY_CODE, for a scripted setup).
   ${CMD} graphs [--sync-server <url>]
-      List the synced graphs each signed-in account can reach, by name and id.
+      List the synced graphs each logged-in account can reach, by name and id.
   ${CMD} serve --graph <id or name> [--sync-server <url>] [--no-semantic]
       Serve one synced graph to an agent over stdio. For Claude Code:
         claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server <url> --graph <id>
@@ -17670,9 +19053,9 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
   ${CMD} diagrams status
       Which browser a publish would use, if any.
 
-This machine can be signed in to several Sync Servers at once (a self-hosted one beside the
-managed service, say); --sync-server says which one a command means, and can be left out
-while only one is signed in. The config file is ${defaultConfigPath()} (override with
+This machine can hold logins for several Sync Servers at once; --sync-server says which one
+a command means, and can be left out while there is only one. The config file is
+${defaultConfigPath()} (override with
 ETHERPK_MCP_CONFIG); cached graphs live under ~/.cache/etherpk/mcp (override with
 ETHERPK_MCP_CACHE_DIR).
 Docs: https://docs.etherpk.com/using-ai-agents-with-your-notes
@@ -17681,8 +19064,12 @@ function fail(message) {
 	console.error(message);
 	process.exit(1);
 }
-async function ask(question, { secret = false } = {}) {
-	if (!process.stdin.isTTY) fail(`${question} - no terminal to ask on; pass it as an option.`);
+/**
+* Ask on the terminal; `hint` says how to give the answer when there is none (a script, or
+* an agent starting the process), since each question has its own option or variable.
+*/
+async function ask(question, { secret = false, hint }) {
+	if (!process.stdin.isTTY) fail(`${question.replace(/:\s*$/, "")}: no terminal to ask on; ${hint}.`);
 	if (!secret) {
 		const rl = createInterface({
 			input: process.stdin,
@@ -17730,24 +19117,30 @@ function requireServer(config, wanted) {
 	if (selection.ok) return selection.credentials;
 	switch (selection.reason) {
 		case "none": return fail(`Not logged in on this machine. Run: ${CMD} login --sync-server <url>`);
-		case "unknown": return fail(`Not logged in to ${selection.syncServer}. Signed in to: ${selection.known.join(", ") || "(none)"}. Run: ${CMD} login --sync-server ${selection.syncServer}`);
-		case "ambiguous": return fail(`Signed in to more than one Sync Server here: ${selection.known.join(", ")}. Say which with --sync-server <url>.`);
+		case "unknown": return fail(`Not logged in to ${selection.syncServer}. Logged in to: ${selection.known.join(", ") || "(none)"}. Run: ${CMD} login --sync-server ${selection.syncServer}`);
+		case "ambiguous": return fail(`Logged in to more than one Sync Server here: ${selection.known.join(", ")}. Say which with --sync-server <url>.`);
 	}
 }
 async function login(args) {
 	const path = defaultConfigPath();
 	const config = await readConfig(path) ?? emptyConfig();
 	const known = Object.keys(config.servers);
-	const syncServer = normaliseSyncServer(args["sync-server"] ?? (known.length === 1 ? known[0] : await ask("Sync Server URL: ")));
+	const syncServer = normaliseSyncServer(args["sync-server"] ?? (known.length === 1 ? known[0] : await ask("Sync Server URL: ", { hint: "pass --sync-server <url>" })));
 	if (!/^https?:\/\//.test(syncServer)) fail("The Sync Server must be an http(s) URL.");
-	const pat = args.pat ?? process.env.ETHERPK_PAT ?? await ask(`Personal Access Token (account-wide, from ${syncServer}/account/tokens): `, { secret: true });
+	const pat = args.pat ?? process.env.ETHERPK_PAT ?? await ask(`Personal Access Token (account-wide, from ${syncServer}/account/tokens): `, {
+		secret: true,
+		hint: "set ETHERPK_PAT or pass --pat <token>"
+	});
 	if (!pat) fail("A Personal Access Token is required.");
 	const account = await connectAccount({
 		syncServer,
 		pat
 	});
-	console.log(`Signed in to ${syncServer} as ${account.principal.email ?? account.principal.name ?? account.principal.id}.`);
-	const byRecoveryCode = async () => unlockByRecoveryCode(account.api, process.env.ETHERPK_RECOVERY_CODE ?? await ask("Recovery Code: ", { secret: true }));
+	console.log(`Connected to ${syncServer} as ${account.principal.email ?? account.principal.name ?? account.principal.id}.`);
+	const byRecoveryCode = async () => unlockByRecoveryCode(account.api, process.env.ETHERPK_RECOVERY_CODE ?? await ask("Recovery Code: ", {
+		secret: true,
+		hint: "set ETHERPK_RECOVERY_CODE"
+	}));
 	const vaultKey = args["recovery-code"] ? await byRecoveryCode() : await approveOrFallBack(account, byRecoveryCode);
 	config.servers[syncServer] = {
 		pat,
@@ -17756,7 +19149,7 @@ async function login(args) {
 	await writeConfig(path, config);
 	console.log(`Keys unlocked and cached in ${path} (owner-only). Anyone who can read your files on this machine can read this account, as with a signed-in browser.`);
 	const others = Object.keys(config.servers).filter((server) => server !== syncServer);
-	if (others.length > 0) console.log(`Also signed in to ${others.join(", ")}; commands now need --sync-server <url> to say which.`);
+	if (others.length > 0) console.log(`Also logged in to ${others.join(", ")}; commands now need --sync-server <url> to say which.`);
 	await listGraphs({
 		syncServer,
 		pat,
@@ -17770,23 +19163,23 @@ async function login(args) {
 * code instead; without a terminal the wait runs to its outcome.
 */
 async function approveOrFallBack(account, byRecoveryCode) {
-	const abort = new AbortController();
+	const controls = approvalWaitControls();
 	const io = {
 		say: (line) => console.log(line),
-		sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
-		signal: abort.signal,
+		sleep: (ms) => sleepUnlessAborted(ms, controls.signal),
+		signal: controls.signal,
 		clientUrl: account.clientUrl
 	};
 	const stdin = process.stdin;
 	const interactive = stdin.isTTY === true;
-	const onKey = (chunk) => {
-		const key = chunk.toString("utf8");
-		if (key === "r" || key === "R") abort.abort();
-		if (key === "") {
-			console.log("");
-			process.exit(130);
-		}
-	};
+	const onKey = (chunk) => controls.onKey(chunk.toString("utf8"));
+	const quitSignals = [
+		"SIGINT",
+		"SIGTERM",
+		"SIGHUP"
+	];
+	const onSignal = (name) => controls.onSignal(name);
+	for (const name of quitSignals) process.once(name, onSignal);
 	if (interactive) {
 		console.log("(Press r to type your Recovery Code instead.)");
 		stdin.setRawMode(true);
@@ -17800,12 +19193,17 @@ async function approveOrFallBack(account, byRecoveryCode) {
 		if (!(error instanceof ApprovalAbandoned)) throw error;
 		abandoned = true;
 	} finally {
+		for (const name of quitSignals) process.off(name, onSignal);
 		if (interactive) {
 			stdin.off("data", onKey);
 			stdin.setRawMode(false);
 			stdin.pause();
 		}
 	}
+	if (controls.exitCode !== null) {
+		console.log("");
+		process.exit(controls.exitCode);
+	}
 	if (!abandoned) throw new Error("unreachable");
 	console.log("Approval cancelled; unlocking with your Recovery Code instead.");
 	return byRecoveryCode();
@@ -17922,7 +19320,13 @@ async function publishCommand(args) {
 		"no-semantic": true
 	};
 	const { graph, graphName } = folder ? await openFolderForServe(folder, quiet) : await openSyncedForServe(wanted, quiet);
+	const host = {
+		env: process.env,
+		cmd: CMD,
+		via: "cli"
+	};
 	try {
+		await findPublication(graph, publication, host);
 		const configPath = defaultPublishFoldersPath(process.env);
 		const key = publishGraphKey(graph.backend, graph.graphId);
 		if (args.out?.trim()) {
@@ -17930,11 +19334,8 @@ async function publishCommand(args) {
 			await writePublishFolders(configPath, withPublishFolder(await readPublishFolders(configPath), key, publication, out));
 			console.error(`etherpk-mcp: publish folder for "${publication}" of "${graphName}" set to ${out} (remembered in ${configPath}).`);
 		} else if (!publishFolderOf(await readPublishFolders(configPath), key, publication)) fail(`No publish folder is set for "${publication}" of "${graphName}" on this machine. Pass --out <dir> once; it is remembered.`);
-		const result = await publish(graph, { id: publication }, {
-			env: process.env,
-			cmd: CMD
-		});
-		console.log(JSON.stringify(result, null, 2));
+		const result = await publish(graph, { id: publication }, host);
+		console.log(JSON.stringify(cliPublishOutput(result), null, 2));
 		if (!result.ok) process.exitCode = 1;
 	} catch (error) {
 		if (error instanceof ToolError) fail(`etherpk-mcp: ${error.message}`);
@@ -18016,6 +19417,11 @@ async function openSyncedForServe(wanted, args) {
 	const account = await connectAccount(login);
 	const vault = await openAccountVault(account.api, fromBase64Url(login.vaultKey));
 	const graphs = await account.api.listGraphs();
+	const swept = await removeUnlistedGraphCaches(process.env, account.serverBaseUrl, account.principal.id, graphs.map((graph) => graph.id)).catch((error) => {
+		console.error(`etherpk-mcp: could not tidy the cache of graphs this server no longer lists: ${error instanceof Error ? error.message : String(error)}`);
+		return [];
+	});
+	if (swept.length > 0) console.error(`etherpk-mcp: removed this computer's copy of ${swept.length === 1 ? "a graph" : `${swept.length} graphs`} ${account.serverBaseUrl} no longer lists for you: ${swept.join(", ")}.`);
 	let graphId = graphs.find((graph) => graph.id === wanted)?.id;
 	let graphName = null;
 	if (!graphId) {
@@ -18027,6 +19433,8 @@ async function openSyncedForServe(wanted, args) {
 	}
 	if (!graphId) fail(`No synced graph on ${login.syncServer} is named or identified by "${wanted}". Run: ${CMD} graphs`);
 	const { record, keyring } = resolveGraphById(graphs, vault, graphId);
+	const persistDir = graphCacheDir(process.env, account.serverBaseUrl, graphId);
+	await stampGraphCacheOwner(persistDir, account.principal.id);
 	console.error(`etherpk-mcp: opening graph ${graphId} on ${account.serverBaseUrl}…`);
 	const graph = await openHeadlessGraph({
 		graphId,
@@ -18036,11 +19444,12 @@ async function openSyncedForServe(wanted, args) {
 		token: account.tokenFor(graphId),
 		presenceName: `Agent on ${hostname()}`,
 		readyTimeoutMs: 2e4,
-		persistDir: graphCacheDir(process.env, account.serverBaseUrl, graphId),
+		persistDir,
 		assets: { baseUrl: account.serverBaseUrl },
 		embeddingModel: embeddingModelFor(args),
 		onSemanticProgress: reportSemanticProgress,
 		onError: (error) => console.error(`etherpk-mcp: ${error.message}`),
+		onAccessLost: (loss) => console.error(loss.kind === "membership" ? `etherpk-mcp: ${account.serverBaseUrl} ended this account's access to graph ${graphId}: it left, was removed, or the graph was deleted. Stopped syncing. Run: ${CMD} graphs` : `etherpk-mcp: the token for ${account.serverBaseUrl} was revoked or is no longer valid. Stopped syncing. Run: ${CMD} login --sync-server ${login.syncServer}`),
 		publishName: createGraphNamePublisher({
 			api: account.api,
 			keyring,