@appsoftwareltd/etherpk-mcp 0.8.1 → 0.8.2

package/dist/main.js

@@ -34,7 +34,7 @@ import { request } from "node:https";
 import { BlockList, isIP } from "node:net";
 var package_default = {
 	name: "@appsoftwareltd/etherpk-mcp",
-	version: "0.8.1",
+	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",
@@ -635,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();
 	}
@@ -674,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", {
@@ -688,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" }),
@@ -785,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,
@@ -806,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: {
@@ -2575,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;
@@ -2596,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;
 	}
@@ -2647,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),
@@ -2686,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,
@@ -2724,6 +2776,7 @@ function insertDerived(db, pageId, doc) {
 		hashText(passage.text),
 		passage.text
 	]);
+	return searchable;
 }
 /**
 * Write one document's [[Task Concept]] rows (ADR 0051).
@@ -2768,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;
@@ -2822,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;
 	});
 }
@@ -2857,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]);
@@ -2887,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). */
@@ -3218,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]);
@@ -3238,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 = {
@@ -3918,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);
@@ -4244,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")), {
@@ -4733,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,
@@ -4749,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), {
@@ -4774,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()
@@ -4803,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,
@@ -5015,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()
@@ -5169,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
 /**
@@ -5210,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;
@@ -5296,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();
@@ -5382,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",
@@ -5442,6 +5639,7 @@ function createDocSync(deps) {
 			lastAttemptAt: null
 		};
 		durableQueue.push(durable);
+		queueChanged();
 		if (operation.kind === "resurrect") lifecycleState = "resurrecting";
 		await transmit(durable);
 	}
@@ -5695,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) {
@@ -5730,6 +5929,7 @@ function createDocSync(deps) {
 						scheduleAutomaticCompaction();
 					}
 					durableQueue.shift();
+					queueChanged();
 					send({
 						type: "ack_confirm",
 						outboxId: message.outboxId
@@ -5760,6 +5960,7 @@ function createDocSync(deps) {
 							}
 							await persist.purge();
 							durableQueue = [];
+							queueChanged();
 							boundarySnapshots.clear();
 							recoveredDirtyTokens.clear();
 							activeDirtyToken = void 0;
@@ -5825,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 = {
@@ -5850,6 +6052,7 @@ function createDocSync(deps) {
 				attemptCount: 0,
 				lastAttemptAt: null
 			});
+			queueChanged();
 			await transmit(durableQueue[0]);
 		},
 		lifecycle: () => lifecycleState,
@@ -5857,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;
@@ -5877,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();
@@ -6066,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. */
@@ -6478,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,
@@ -6499,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
@@ -6509,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;
@@ -6526,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({
@@ -6544,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,
@@ -6558,7 +6881,7 @@ function createGraphSync(deps) {
 					}));
 				});
 			} catch (error) {
-				if (error instanceof WatermarkConnectionInterruptedError && !disposed) continue;
+				if (error instanceof WatermarkConnectionInterruptedError && !disposed && !lost) continue;
 				throw error;
 			}
 		}
@@ -6620,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);
@@ -6655,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;
@@ -6663,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", {
@@ -6670,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) {
@@ -6678,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"),
@@ -6686,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";
 				}
@@ -6782,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();
@@ -6801,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();
 			}
@@ -6824,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") {
@@ -6834,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();
@@ -6868,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();
@@ -7064,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) {
@@ -7105,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,
@@ -7138,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) {
@@ -7162,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;
@@ -7649,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
@@ -9065,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(".");
@@ -9504,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;
@@ -9572,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 {
@@ -10019,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
@@ -10343,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;
@@ -10353,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)
@@ -10462,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,
@@ -10565,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();
@@ -10724,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,
@@ -10738,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) {
@@ -10800,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();
@@ -11000,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. */
@@ -11014,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. */
@@ -11033,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 = [];
@@ -11092,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;
 	}
@@ -11105,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);
@@ -11401,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;
@@ -11415,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);
@@ -11528,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);
@@ -11799,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);
@@ -11889,7 +12589,11 @@ 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";
@@ -11960,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 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 readAssetBytes(ref) {
+	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),
@@ -11978,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()),
@@ -12069,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));
@@ -12085,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);
@@ -12129,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
@@ -12247,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),
@@ -12282,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 });
@@ -12364,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,
@@ -12399,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,
@@ -12676,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
@@ -12747,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;
@@ -12773,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
@@ -12898,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;
@@ -13559,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
@@ -14622,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,
@@ -14711,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",
@@ -15088,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;
@@ -15102,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);
@@ -15210,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,
@@ -15355,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 {
@@ -15955,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();
@@ -16195,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 {
@@ -16669,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 {
@@ -16772,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\".");
@@ -16786,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 {
@@ -16796,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}"`;
@@ -16851,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);
@@ -17480,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. */
@@ -17499,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
@@ -17731,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", {
@@ -18013,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.
@@ -18032,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>
@@ -18074,8 +19053,8 @@ 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; --sync-server says which one
-a command means, and can be left out while only one is signed in. The config file is
+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).
@@ -18085,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,
@@ -18134,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,
@@ -18160,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,
@@ -18174,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);
@@ -18204,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();
@@ -18326,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()) {
@@ -18334,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}`);
@@ -18420,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) {
@@ -18431,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,
@@ -18440,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,