busa-cli 0.30.1 → 0.40.1

package/dist/{update-check-DXT4d-yb.js → update-check-CDXOWtw_.js}

@@ -6,11 +6,11 @@ import { DEFAULT_BASE_URL, cloudContract, createBusabaseClient, getRecordByField
 import { Command, CommanderError, InvalidArgumentError, Option } from "commander";
 import { createInterface } from "node:readline/promises";
 import { homedir, tmpdir } from "node:os";
+import { access, mkdir, mkdtemp, open, readFile, readdir, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { PassThrough, Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { ZstdCompress, ZstdDecompress } from "node:zlib";
 import * as tar from "tar-stream";
-import { mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { spawn } from "node:child_process";
 import { createServer } from "node:http";
 import { parse, stringify } from "yaml";
@@ -3003,19 +3003,55 @@ z.object({
 	textContentHash: z.string().nullable(),
 	byteCount: z.number().int().nonnegative()
 });
+z.object({ nodeIds: z.array(z.string()).min(1).max(25) });
 z.object({ 
 /**
-* The space id the archive was ORIGINALLY exported from (`manifest.spaceId`
-* in the `.bbdump`, already integrity-verified before this is called).
-* `importTableRows`'s "nodes" handling needs this to recognize the
-* archive's own root-node row deterministically (`rootNodeIdForSpace`) —
-* scanning each batch's rows for "the one with a null `parentId`" only
-* works when that row happens to land in the SAME batch as its children,
-* which cursor pagination (id-ordered, not tree-ordered) does not
-* guarantee once a space has more nodes than one page. See the matching
-* comment in `import-logic.ts`.
-*/
-sourceSpaceId: z.string() });
+* One entry per requested node that is a Doc in this space. A node id that
+* does not resolve is simply absent (not an error): the caller asked for a
+* batch, and one bad id must not cost it the other 24. A Doc that exists but
+* has no body object yet yields `markdown: ""`, matching what a read through
+* the Doc domain would return.
+*/
+bodies: z.array(z.object({
+	nodeId: z.string(),
+	markdown: z.string()
+})) });
+z.object({
+	/**
+	* The space id the archive was ORIGINALLY exported from (`manifest.spaceId`
+	* in the `.bbdump`, already integrity-verified before this is called).
+	* `importTableRows`'s "nodes" handling needs this to recognize the
+	* archive's own root-node row deterministically (`rootNodeIdForSpace`) —
+	* scanning each batch's rows for "the one with a null `parentId`" only
+	* works when that row happens to land in the SAME batch as its children,
+	* which cursor pagination (id-ordered, not tree-ordered) does not
+	* guarantee once a space has more nodes than one page. See the matching
+	* comment in `import-logic.ts`.
+	*/
+	sourceSpaceId: z.string(),
+	/**
+	* Continue a restore that was interrupted partway through, instead of
+	* requiring an empty space.
+	*
+	* A restore that FAILS rolls itself back (`importAbort`), so the target is
+	* left clean and a plain re-run works. What cannot roll itself back is a
+	* restore whose process died — Ctrl-C, OOM, a dropped connection, the
+	* machine rebooting. That leaves the space holding however many of the
+	* archive's rows had landed, and every subsequent attempt is refused
+	* ("requires an empty target space") with no way forward except wiping it.
+	*
+	* In this mode the empty-space guard is skipped and inserts become
+	* `ON CONFLICT DO NOTHING`, so replaying the same archive re-lands only what
+	* is missing. Blobs and doc bodies are content-addressed writes to object
+	* storage and were already idempotent.
+	*
+	* DANGEROUS if pointed at the wrong space: rows that collide are silently
+	* skipped rather than reported, so restoring archive A into a space holding
+	* archive B's data would interleave the two instead of refusing. Only pass
+	* it to continue the SAME archive into the SAME space.
+	*/
+	resume: z.boolean().optional().default(false)
+});
 z.object({ sessionId: z.string() });
 z.object({
 	sessionId: z.string(),
@@ -3034,6 +3070,85 @@ z.object({
 	warnings: z.array(z.string())
 });
 z.object({ ok: z.boolean() });
+//#endregion
+//#region src/retry.ts
+const BASE_DELAY_MS = 500;
+const MAX_DELAY_MS = 2e4;
+const READ_METHODS = /* @__PURE__ */ new Set([
+	"GET",
+	"HEAD",
+	"OPTIONS"
+]);
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const isNetworkError = (error) => error instanceof TypeError || /fetch failed|econnreset|econnrefused|etimedout|socket hang up/i.test(error instanceof Error ? error.message : String(error));
+/**
+* Whether an already-thrown error is worth another attempt.
+*
+* `shouldRetry` below decides from a `Response`; this decides from an `Error`,
+* for callers that retry ABOVE the fetch layer (see `backup`'s exporter, which
+* has to retry oRPC reads that `withRetry` refuses to repeat because they are
+* POSTs). The distinction that matters is transient-vs-deterministic: a dropped
+* socket or a 502 may answer differently next time, while a 404, a validation
+* refusal or a shape mismatch answers identically every time — retrying those
+* only burns the backoff, which at scale (one per attachment, on a space with
+* tens of thousands) is the difference between a slow backup and a stalled one.
+*/
+function isTransientError(error) {
+	if (isNetworkError(error)) return true;
+	const status = error?.status;
+	if (typeof status === "number") return status === 429 || status >= 500;
+	return /\bHTTP (429|5\d\d)\b/.test(error instanceof Error ? error.message : String(error));
+}
+/** `Retry-After` is either delay-seconds or an HTTP-date; both are legal. */
+function parseRetryAfter(header, now = Date.now()) {
+	if (!header) return void 0;
+	const seconds = Number(header.trim());
+	if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1e3, MAX_DELAY_MS);
+	const at = Date.parse(header);
+	if (Number.isNaN(at)) return void 0;
+	return Math.min(Math.max(at - now, 0), MAX_DELAY_MS);
+}
+/** Whether this outcome is worth another attempt for a request using `method`. */
+function shouldRetry(method, status) {
+	if (status === 429) return true;
+	if (!READ_METHODS.has(method.toUpperCase())) return false;
+	return status === void 0 || status >= 500;
+}
+/**
+* Wrap a fetch so transient failures are retried with exponential backoff.
+* Returns `base` unchanged when `retries` is 0, so the no-retry path adds no
+* wrapper and no behaviour.
+*/
+function withRetry(base, options) {
+	const { retries } = options;
+	if (retries <= 0) return base;
+	const sleep = options.sleep ?? defaultSleep;
+	const notify = options.notify ?? ((message) => console.error(message));
+	const jitter = options.jitter ?? Math.random;
+	return (async (input, init) => {
+		const method = init?.method ?? (input instanceof Request ? input.method : "GET");
+		for (let attempt = 0;; attempt += 1) {
+			let response;
+			let failure;
+			try {
+				response = await base(input, init);
+			} catch (error) {
+				if (!isNetworkError(error)) throw error;
+				failure = error;
+			}
+			const status = response?.status;
+			const last = attempt >= retries;
+			if (!shouldRetry(method, status) || last) {
+				if (response) return response;
+				throw failure;
+			}
+			const backoff = Math.min(BASE_DELAY_MS * 2 ** attempt, MAX_DELAY_MS);
+			const delay = parseRetryAfter(response?.headers.get("retry-after") ?? null) ?? Math.round(backoff * (.5 + jitter() * .5));
+			notify(`[busabase-cli] ${status ? `HTTP ${status}` : "connection failed"} — retrying in ${Math.round(delay / 1e3)}s (attempt ${attempt + 2} of ${retries + 1})`);
+			await sleep(delay);
+		}
+	});
+}
 /**
 * `.bbdump` manifest — the archive's own table of contents + integrity
 * record. Written last (after every entry's bytes/checksums are known) so it
@@ -3424,9 +3539,12 @@ async function streamNdjsonRows(body, send) {
 * integrity-verified (`verifyArchive`) before this is called.
 */
 async function importFull(options) {
-	const { client, archivePath, sourceSpaceId, onProgress } = options;
+	const { client, archivePath, sourceSpaceId, resume = false, onProgress } = options;
 	const log = onProgress ?? (() => {});
-	const { sessionId } = await client.dump.importBegin({ sourceSpaceId });
+	const { sessionId } = await client.dump.importBegin({
+		sourceSpaceId,
+		resume
+	});
 	try {
 		const docBodyRows = [];
 		await streamArchive(archivePath, async (entry) => {
@@ -3483,7 +3601,7 @@ async function importFull(options) {
 		}
 		return await client.dump.importCommit({ sessionId });
 	} catch (error) {
-		await client.dump.importAbort({ sessionId }).catch(() => void 0);
+		if (!resume) await client.dump.importAbort({ sessionId }).catch(() => void 0);
 		throw error;
 	}
 }
@@ -3500,33 +3618,285 @@ async function importFull(options) {
 * the one page here, close to the failure, rather than widening the shared
 * fetch-level wrapper (which would change retry behavior for every command).
 */
-const PAGE_FETCH_RETRIES = 3;
+const DEFAULT_PAGE_FETCH_RETRIES = 3;
 const PAGE_FETCH_RETRY_DELAY_MS = 1e3;
-const fetchPageWithRetry = async (fetchPage, onRetry) => {
+const fetchPageWithRetry = async (fetchPage, onRetry, shouldRetryError = () => true, retries = DEFAULT_PAGE_FETCH_RETRIES) => {
 	for (let attempt = 0;; attempt += 1) try {
 		return await fetchPage();
 	} catch (error) {
-		if (attempt >= PAGE_FETCH_RETRIES) throw error;
+		if (!shouldRetryError(error)) throw error;
+		if (attempt >= retries) throw error;
 		onRetry?.(attempt + 1, error);
 		await new Promise((resolve) => setTimeout(resolve, PAGE_FETCH_RETRY_DELAY_MS * (attempt + 1)));
 	}
 };
 /**
+* A per-item loop (one doc body, one attachment blob, one asset-text blob —
+* always exactly one request each, no server-side batching available) can run
+* for many minutes on a real space with no output between its start and its
+* own final summary line, which reads exactly like a hang. Call this once per
+* iteration; it logs `message()` only every `PROGRESS_INTERVAL_MS`, not on
+* every single item.
+*/
+const PROGRESS_INTERVAL_MS = 5e3;
+const throttledProgress = (log, message) => {
+	let lastAt = Date.now();
+	return () => {
+		const now = Date.now();
+		if (now - lastAt < PROGRESS_INTERVAL_MS) return;
+		lastAt = now;
+		log(message());
+	};
+};
+/**
+* How many blob downloads may be in flight at once.
+*
+* The export used to be strictly one-request-at-a-time. On the real Vika Team
+* space that is 10,486 attachments x 2 sequential round trips each (resolve a
+* download URL, then fetch the bytes) — ~21k serialized requests, which is
+* where the bulk of a multi-HOUR backup went. Latency, not bandwidth, was the
+* limit: a single in-flight download never comes close to saturating the link.
+*
+* 8 is deliberately modest. These run against a live production server that is
+* also serving real users, and each in-flight download holds its whole body in
+* memory (see the buffer in the attachment loop), so the ceiling also bounds
+* peak heap at roughly 8 x the largest file rather than the whole set.
+*/
+const BLOB_DOWNLOAD_CONCURRENCY = 8;
+/**
+* Run `work` over `items` with at most `limit` in flight, handing each result
+* to `consume` strictly IN ORDER and one at a time.
+*
+* The ordering guarantee is what makes this safe to drop into the existing
+* loops: `consume` keeps doing exactly what the sequential body did (append to
+* a spool file, bump counters, dedupe against a Set), with no concurrent
+* access to any of it — only the network wait overlaps. Ordered output also
+* keeps an archive's bytes reproducible for a given space rather than varying
+* with which download happened to finish first.
+*
+* A rejected `work` is captured rather than thrown, so one bad item still
+* reaches `consume` as a failure and the run continues — the loops below
+* already treat a single unreachable blob as a warning, not a reason to lose
+* the other 10,485.
+*/
+const forEachConcurrent = async (items, limit, work, consume) => {
+	const inFlight = /* @__PURE__ */ new Map();
+	let started = 0;
+	for (let emitted = 0; emitted < items.length; emitted += 1) {
+		while (inFlight.size < limit && started < items.length) {
+			const index = started;
+			started += 1;
+			inFlight.set(index, work(items[index]).then((value) => ({
+				ok: true,
+				value
+			}), (error) => ({
+				ok: false,
+				error
+			})));
+		}
+		const pending = inFlight.get(emitted);
+		inFlight.delete(emitted);
+		await consume(await pending, items[emitted]);
+	}
+};
+/**
 * Write an NDJSON archive entry from already-collected rows without ever
 * concatenating them into a single JS string first. A real production table
 * (e.g. `fieldValues` holding long CMS/article-body content) can produce an
 * NDJSON blob well past V8's max string length — `"".join("\n")` on such a
 * table throws `RangeError: Invalid string length` and aborts the whole
-* backup. Building one `Buffer` per line and streaming them through
-* `ArchiveWriter.addStream` (already built for exactly this — see its own
-* doc comment) avoids ever holding one oversized string/buffer.
+* backup. Streaming line-sized buffers through `ArchiveWriter.addStream`
+* (already built for exactly this — see its own doc comment) avoids ever
+* holding one oversized string/buffer.
+*
+* `addStream` needs the entry's total byte size up front (a tar constraint),
+* which used to be met by materializing every line as a `Buffer` in an array
+* and summing it. On `fieldValues` that is 1.1M `Buffer`s alive at once while
+* the 1.1M row objects they came from are also still live — the same
+* peak-heap shape `SpooledNdjsonEntry` was written to avoid, on the one table
+* that dwarfs the rest. Measure the size in a first pass (keeping only a
+* running total), then re-serialize lazily from a generator so at most one
+* line exists at a time. The cost is `JSON.stringify` twice per row, which is
+* CPU against a backup whose real bottleneck is the network.
 */
 const writeNdjsonEntry = async (writer, path, rows) => {
-	const lineBuffers = rows.map((row) => Buffer.from(`${JSON.stringify(row)}\n`, "utf8"));
-	const totalSize = lineBuffers.reduce((sum, buf) => sum + buf.length, 0);
-	await writer.addStream(path, totalSize, Readable.from(lineBuffers));
+	let totalSize = 0;
+	for (const row of rows) totalSize += Buffer.byteLength(`${JSON.stringify(row)}\n`, "utf8");
+	const lines = function* () {
+		for (const row of rows) yield Buffer.from(`${JSON.stringify(row)}\n`, "utf8");
+	};
+	await writer.addStream(path, totalSize, Readable.from(lines()));
+};
+/**
+* Same NDJSON-entry shape as {@link writeNdjsonEntry}, but for a table built
+* one row at a time over a long fetch loop (attachment blobs, asset-text
+* blobs) instead of already sitting in memory. `ArchiveWriter.addStream`
+* requires the entry's total byte size up front (a tar constraint), which is
+* why `writeNdjsonEntry` collects every row into an array first — fine for
+* table rows, but a real space's attachment blobs (base64-encoded, one row
+* per file) can total many GB. Held as an array of Buffers so their combined
+* size could be summed, that blew Node's default heap outright — confirmed
+* live: "JavaScript heap out of memory" partway through a ~5.7GB attachment
+* set. Spooling each row to a temp file as it's produced, then streaming
+* that file into the archive once its final size is known from disk, keeps
+* peak memory bounded by one row at a time rather than the whole table.
+*/
+var SpooledNdjsonEntry = class {
+	path;
+	stream;
+	/**
+	* `spoolPath` is deterministic (derived from the archive path) rather than a
+	* random temp name, so a killed backup leaves a file the next run can find
+	* and continue from — see `recoverCompleteRows`. A random name in `tmpdir()`
+	* left nothing but an orphan nobody could match back to its archive.
+	*/
+	constructor(spoolPath, append) {
+		this.path = spoolPath;
+		this.stream = createWriteStream(this.path, append ? { flags: "a" } : {});
+	}
+	async writeRow(row) {
+		const buf = Buffer.from(`${JSON.stringify(row)}\n`, "utf8");
+		if (!this.stream.write(buf)) await new Promise((resolve) => this.stream.once("drain", resolve));
+	}
+	async finish(writer, archivePath) {
+		await new Promise((resolve, reject) => {
+			this.stream.end((error) => error ? reject(error) : resolve());
+		});
+		const { size } = await stat(this.path);
+		await writer.addStream(archivePath, size, createReadStream(this.path));
+		await unlink(this.path);
+	}
+};
+/**
+* What a previous, killed run already spooled: the identifying key of every
+* COMPLETE row, plus the totals those rows represent.
+*
+* "Complete" is load-bearing. A process killed mid-write leaves a final line
+* with no trailing newline — valid-looking JSON prefix, truncated content. The
+* file is therefore truncated back to its last newline before anything is
+* appended, so a resumed run can never splice new output onto half a row.
+*
+* Byte totals are recomputed from the base64 lengths WITHOUT decoding: a real
+* space's spool is ~5.7GB, and decoding it just to re-derive a counter would
+* cost more than re-downloading. base64 encodes 3 bytes per 4 chars, minus one
+* byte per `=` of padding.
+*/
+/**
+* Suffixes of the two spool files a backup writes next to its archive, in the
+* order `exportFull` derives them (attachment blobs, then asset-text blobs).
+* Exported so `commands.ts` can detect leftovers from an interrupted run
+* without duplicating the naming.
+*/
+const SPOOL_SUFFIXES = [".attachment-blobs.part", ".asset-text-blobs.part"];
+const decodedBase64Bytes = (base64) => {
+	const padding = base64.endsWith("==") ? 2 : base64.endsWith("=") ? 1 : 0;
+	return Math.max(0, base64.length * 3 / 4 - padding);
+};
+const recoverCompleteRows = async (spoolPath, keyField) => {
+	const keys = /* @__PURE__ */ new Set();
+	let count = 0;
+	let bytes = 0;
+	let completeBytes = 0;
+	let handle;
+	try {
+		handle = await open(spoolPath, "r+");
+	} catch {
+		return {
+			keys,
+			count,
+			bytes
+		};
+	}
+	try {
+		let carry = "";
+		for await (const chunk of handle.createReadStream({
+			encoding: "utf8",
+			autoClose: false
+		})) {
+			carry += chunk;
+			let newlineIndex;
+			while ((newlineIndex = carry.indexOf("\n")) !== -1) {
+				const line = carry.slice(0, newlineIndex);
+				carry = carry.slice(newlineIndex + 1);
+				completeBytes += Buffer.byteLength(line, "utf8") + 1;
+				if (!line) continue;
+				let row;
+				try {
+					row = JSON.parse(line);
+				} catch {
+					completeBytes -= Buffer.byteLength(line, "utf8") + 1;
+					carry = "";
+					break;
+				}
+				const key = row[keyField];
+				if (typeof key !== "string") continue;
+				keys.add(key);
+				count += 1;
+				bytes += decodedBase64Bytes(typeof row.base64 === "string" ? row.base64 : "");
+			}
+		}
+		await handle.truncate(completeBytes);
+	} finally {
+		await handle.close();
+	}
+	return {
+		keys,
+		count,
+		bytes
+	};
 };
 const EXPORT_TABLES = [...DumpTableSchema.options];
+/**
+* Which dump tables reference which OTHER dump tables, column by column —
+* mirrors the real `.references()` declarations in busabase-core's schema
+* (`domains/base/schema.ts`, `domains/assets/schema/assets.ts`,
+* `db/schema.ts`). Only cross-table FKs matter here: a column with no
+* `.references()` (e.g. `fieldValues.fieldId`, a loose text ref by design, or
+* `assetUsages.recordId`, which defaults to `""`) cannot throw a violation and
+* must NOT be listed, or the drift check would drop rows Postgres would have
+* accepted.
+*
+* `nodes.parentId` is deliberately absent despite being a real self-FK: the
+* importer rewrites it (dropping the source root and remapping its children
+* onto the target's own root — see `import-logic.ts`), so a parentId that
+* looks dangling here is resolved server-side.
+*/
+const DUMP_FOREIGN_KEYS = {
+	bases: { nodeId: "nodes" },
+	baseFields: { baseId: "bases" },
+	views: { baseId: "bases" },
+	records: {
+		baseId: "bases",
+		headCommitId: "commits"
+	},
+	fieldValues: {
+		baseId: "bases",
+		recordId: "records",
+		changeRequestId: "changeRequests",
+		operationId: "operations",
+		commitId: "commits"
+	},
+	recordLinks: {
+		baseId: "bases",
+		fieldId: "baseFields",
+		sourceRecordId: "records",
+		targetBaseId: "bases",
+		targetRecordId: "records",
+		commitId: "commits"
+	},
+	assetUsages: {
+		assetId: "assets",
+		nodeId: "nodes"
+	},
+	assetTexts: { assetId: "assets" },
+	auditEvents: {
+		baseId: "bases",
+		recordId: "records",
+		changeRequestId: "changeRequests",
+		operationId: "operations",
+		commitId: "commits"
+	}
+};
 const HISTORY_TABLES = [
 	"commits",
 	"changeRequests",
@@ -3536,6 +3906,84 @@ const HISTORY_TABLES = [
 	"auditEvents"
 ];
 /**
+* A change request in one of these states is FINISHED — its content is history.
+* Anything else (`in_review`, `approved`, `conflict`, …) is work somebody has
+* not finished yet, and a backup that silently dropped it would lose a
+* colleague's in-flight work, not history. On the validated production space
+* that is 492 unfinished out of 22,828.
+*/
+const FINISHED_CR_STATUSES = /* @__PURE__ */ new Set([
+	"merged",
+	"closed",
+	"rejected"
+]);
+/**
+* Reduce the history tables to what the CURRENT state (plus unfinished work)
+* genuinely needs, for `--no-history`.
+*
+* The flag used to just omit the history tables wholesale, which produced an
+* archive that could never be restored: `records.head_commit_id` is a NOT NULL
+* FK into `commits`, so every record dangled. Verified end-to-end — the
+* restore died on the first `records` batch. Dropping a table a live table
+* still points at is not "less history", it is a broken archive.
+*
+* What the shape of the data actually allows (measured on the real Vika Team
+* space, 1,130,898 fieldValues rows):
+*  - Every (record, field) cell holds exactly ONE row — there are no
+*    per-field historical versions to drop. 499,186 rows carry a `recordId`
+*    and ARE the current values.
+*  - The other 631,712 rows carry no `recordId` at all: they are values staged
+*    inside change requests ("this CR proposes setting X to Y"). Those are the
+*    history, and they are 56% of the table.
+*  - 97.8% of change requests are already merged.
+*
+* So: keep every current value, keep unfinished change requests whole, and
+* drop the finished ones' contents. Commits are then kept transitively —
+* whatever the surviving rows still reference — rather than by any rule about
+* what a commit "is", so a NOT NULL `commitId` can never be left dangling.
+*/
+const pruneToCurrentState = (tableRows, tableCounts, log) => {
+	const before = Object.fromEntries(HISTORY_TABLES.map((t) => [t, (tableRows[t] ?? []).length]));
+	const beforeFieldValues = (tableRows.fieldValues ?? []).length;
+	const keptCrIds = new Set((tableRows.changeRequests ?? []).filter((cr) => !FINISHED_CR_STATUSES.has(cr.status)).map((cr) => cr.id));
+	const keptOperations = (tableRows.operations ?? []).filter((op) => keptCrIds.has(op.changeRequestId));
+	const keptOpIds = new Set(keptOperations.map((op) => op.id));
+	const keptFieldValues = (tableRows.fieldValues ?? []).filter((fv) => {
+		if (fv.recordId) return true;
+		if (fv.changeRequestId && keptCrIds.has(fv.changeRequestId)) return true;
+		return Boolean(fv.operationId) && keptOpIds.has(fv.operationId);
+	});
+	for (const fv of keptFieldValues) {
+		if (fv.changeRequestId && !keptCrIds.has(fv.changeRequestId)) fv.changeRequestId = null;
+		if (fv.operationId && !keptOpIds.has(fv.operationId)) fv.operationId = null;
+	}
+	const keptReviews = (tableRows.reviews ?? []).filter((r) => keptCrIds.has(r.changeRequestId));
+	const keptComments = (tableRows.comments ?? []).filter((c) => !c.changeRequestId || keptCrIds.has(c.changeRequestId));
+	const neededCommitIds = /* @__PURE__ */ new Set();
+	const need = (id) => {
+		if (typeof id === "string" && id) neededCommitIds.add(id);
+	};
+	for (const r of tableRows.records ?? []) need(r.headCommitId);
+	for (const rl of tableRows.recordLinks ?? []) need(rl.commitId);
+	for (const fv of keptFieldValues) need(fv.commitId);
+	for (const op of keptOperations) need(op.headCommitId);
+	for (const c of keptComments) need(c.commitId);
+	const keptCommits = (tableRows.commits ?? []).filter((c) => neededCommitIds.has(c.id));
+	const assign = (table, rows) => {
+		tableRows[table] = rows;
+		tableCounts[table] = rows.length;
+	};
+	assign("fieldValues", keptFieldValues);
+	assign("changeRequests", (tableRows.changeRequests ?? []).filter((cr) => keptCrIds.has(cr.id)));
+	assign("operations", keptOperations);
+	assign("reviews", keptReviews);
+	assign("comments", keptComments);
+	assign("commits", keptCommits);
+	assign("auditEvents", []);
+	const dropped = (table) => before[table] - (tableRows[table] ?? []).length;
+	log(`  --no-history: kept ${keptFieldValues.length}/${beforeFieldValues} fieldValues (dropped ${beforeFieldValues - keptFieldValues.length} staged in finished change requests), ${keptCrIds.size} unfinished change request(s); dropped ${dropped("commits")} commits, ${dropped("operations")} operations, ${dropped("reviews")} reviews, ${dropped("auditEvents")} audit events.`);
+};
+/**
 * Full-fidelity export: pulls every dump-eligible table via the `dump.exportTables`
 * endpoint (cursor-paginated, raw rows with original ids), doc bodies for
 * every `doc` node via the public `docs.body` read, every asset's bytes via
@@ -3544,16 +3992,18 @@ const HISTORY_TABLES = [
 * keeps the format uniform regardless of table size).
 */
 async function exportFull(options) {
-	const { client, outPath, spaceId, sourceHost, includeHistory, toolVersion, onProgress } = options;
-	const pageLimit = options.pageLimit ?? 500;
+	const { client, outPath, spaceId, sourceHost, includeHistory, toolVersion, resume = false, retries = DEFAULT_PAGE_FETCH_RETRIES, onProgress } = options;
+	const [attachmentSpoolPath, assetTextSpoolPath] = SPOOL_SUFFIXES.map((suffix) => `${outPath}${suffix}`);
+	const pageLimit = options.pageLimit ?? 2e3;
 	const log = onProgress ?? (() => {});
 	const writer = ArchiveWriter.create(outPath);
 	const tableCounts = {};
 	const tableRows = {};
-	const tables = includeHistory ? EXPORT_TABLES : EXPORT_TABLES.filter((t) => !HISTORY_TABLES.includes(t));
+	const tables = EXPORT_TABLES;
 	for (const table of tables) {
 		const rows = [];
 		let cursor;
+		const reportProgress = throttledProgress(log, () => `  ...${table}: ${rows.length} rows so far`);
 		do {
 			const page = await fetchPageWithRetry(() => client.dump.exportTables({
 				table,
@@ -3561,101 +4011,207 @@ async function exportFull(options) {
 				limit: pageLimit
 			}), (attempt, error) => {
 				const message = error instanceof Error ? error.message : String(error);
-				log(`  retrying ${table} page (attempt ${attempt}/${PAGE_FETCH_RETRIES}): ${message}`);
-			});
+				log(`  retrying ${table} page (attempt ${attempt}/${retries}): ${message}`);
+			}, void 0, retries);
 			rows.push(...page.rows);
 			cursor = page.nextCursor ?? void 0;
+			if (cursor) reportProgress();
 		} while (cursor);
 		tableRows[table] = rows;
 		tableCounts[table] = rows.length;
 		log(`exported ${table}: ${rows.length} rows`);
 	}
+	if (!includeHistory) pruneToCurrentState(tableRows, tableCounts, log);
+	{
+		const exported = new Set(tables);
+		const idsOf = (table) => exported.has(table) ? new Set((tableRows[table] ?? []).map((row) => row.id)) : null;
+		const validIds = /* @__PURE__ */ new Map();
+		const validIdsFor = (table) => {
+			if (!validIds.has(table)) validIds.set(table, idsOf(table));
+			return validIds.get(table) ?? null;
+		};
+		for (const table of IMPORT_ORDER) {
+			const foreignKeys = DUMP_FOREIGN_KEYS[table];
+			if (!foreignKeys || !exported.has(table)) continue;
+			const rows = tableRows[table] ?? [];
+			if (rows.length === 0) continue;
+			const kept = rows.filter((row) => Object.entries(foreignKeys).every(([column, targetTable]) => {
+				const id = row[column];
+				if (id === null || id === void 0 || id === "") return true;
+				const valid = validIdsFor(targetTable);
+				return valid === null || valid.has(id);
+			}));
+			const dropped = rows.length - kept.length;
+			if (dropped === 0) continue;
+			log(`  WARNING: dropped ${dropped} ${table} row(s) referencing a ${Object.values(foreignKeys).join("/")} that this archive does not carry — a long backup of an actively-used space can drift out of sync with itself. Re-run the backup for a tighter snapshot if these matter.`);
+			tableRows[table] = kept;
+			tableCounts[table] = kept.length;
+			validIds.set(table, new Set(kept.map((row) => row.id)));
+		}
+	}
 	const docNodes = (tableRows.nodes ?? []).filter((n) => n.type === "doc");
 	const docBodyEntries = [];
 	const skippedDocBodies = [];
-	for (const node of docNodes) {
-		const nodeId = node.id;
-		try {
-			const detail = await client.nodes.get({
-				nodeId,
-				type: "doc"
-			});
-			if (detail.type !== "doc") throw new Error(`Expected a doc node for ${nodeId}, got "${detail.type}"`);
-			docBodyEntries.push({
-				nodeId,
-				body: detail.body ?? ""
-			});
+	const reportDocProgress = throttledProgress(log, () => `  ...doc bodies: ${docBodyEntries.length}/${docNodes.length} fetched`);
+	const isMissingRoute = (error) => /not found|404|no procedure|unknown procedure/i.test(error instanceof Error ? error.message : String(error));
+	const readOneDocBodyLegacy = async (nodeId) => await fetchPageWithRetry(async () => {
+		const detail = await client.nodes.get({
+			nodeId,
+			type: "doc"
+		});
+		if (detail.type !== "doc") throw new Error(`Expected a doc node for ${nodeId}, got "${detail.type}"`);
+		return detail.body ?? "";
+	}, (attempt, error) => log(`  retrying doc body ${nodeId} (attempt ${attempt}/${retries}): ${error instanceof Error ? error.message : String(error)}`), isTransientError, retries);
+	const applyLegacyDocBody = (nodeId, body) => {
+		docBodyEntries.push({
+			nodeId,
+			body
+		});
+	};
+	let batchRouteAvailable = true;
+	for (let i = 0; i < docNodes.length; i += 25) {
+		reportDocProgress();
+		const nodeIds = docNodes.slice(i, i + 25).map((node) => node.id);
+		if (batchRouteAvailable) try {
+			const { bodies } = await fetchPageWithRetry(() => client.dump.exportDocBodies({ nodeIds }), (attempt, error) => log(`    retrying doc bodies batch (attempt ${attempt}): ${error instanceof Error ? error.message : String(error)}`), (error) => !isMissingRoute(error), retries);
+			const byId = new Map(bodies.map((entry) => [entry.nodeId, entry.markdown]));
+			for (const nodeId of nodeIds) {
+				const markdown = byId.get(nodeId);
+				if (markdown === void 0) {
+					skippedDocBodies.push(nodeId);
+					log(`  WARNING: server returned no body for doc node ${nodeId}, skipping it`);
+					continue;
+				}
+				docBodyEntries.push({
+					nodeId,
+					body: markdown
+				});
+			}
+			continue;
 		} catch (error) {
+			if (!isMissingRoute(error)) {
+				const message = error instanceof Error ? error.message : String(error);
+				skippedDocBodies.push(...nodeIds);
+				log(`  WARNING: could not read doc bodies for ${nodeIds.length} node(s), skipping them (${message})`);
+				continue;
+			}
+			batchRouteAvailable = false;
+			log("  NOTE: this server predates `dump.exportDocBodies`; falling back to one request per Doc. Archived Docs cannot be read that way, so their bodies will be missing from this archive — upgrade the server to capture them.");
+		}
+		await forEachConcurrent(nodeIds, BLOB_DOWNLOAD_CONCURRENCY, (nodeId) => readOneDocBodyLegacy(nodeId), (settled, nodeId) => {
+			if (settled.ok) {
+				applyLegacyDocBody(nodeId, settled.value);
+				return;
+			}
+			const { error } = settled;
 			const message = error instanceof Error ? error.message : String(error);
 			skippedDocBodies.push(nodeId);
 			log(`  WARNING: could not read doc body for node ${nodeId}, skipping it (${message})`);
-		}
+		});
 	}
 	log(`fetched ${docBodyEntries.length} doc bodies, skipped ${skippedDocBodies.length}`);
 	const attachmentsById = new Map((tableRows.attachments ?? []).map((a) => [a.id, a]));
-	const attachmentBlobRows = [];
-	let blobCount = 0;
-	let blobBytes = 0;
+	const recoveredBlobs = resume ? await recoverCompleteRows(attachmentSpoolPath, "storageKey") : {
+		keys: /* @__PURE__ */ new Set(),
+		count: 0,
+		bytes: 0
+	};
+	const attachmentBlobs = new SpooledNdjsonEntry(attachmentSpoolPath, resume);
+	let blobCount = recoveredBlobs.count;
+	let blobBytes = recoveredBlobs.bytes;
 	const skippedAssets = [];
-	for (const asset of tableRows.assets ?? []) {
-		const assetId = asset.id;
+	const assetRows = tableRows.assets ?? [];
+	if (recoveredBlobs.count > 0) log(`  resuming: ${recoveredBlobs.count} attachment blob(s) already downloaded (${recoveredBlobs.bytes} bytes), continuing with the rest`);
+	const reportBlobProgress = throttledProgress(log, () => `  ...attachment blobs: ${blobCount}/${assetRows.length} fetched`);
+	await forEachConcurrent(assetRows, BLOB_DOWNLOAD_CONCURRENCY, async (asset) => {
 		const attachment = attachmentsById.get(asset.attachmentId);
-		try {
-			if (!attachment) throw new Error("no matching attachments row (orphaned asset)");
-			const download = await client.assets.download({ assetId });
+		if (!attachment) throw new Error("no matching attachments row (orphaned asset)");
+		if (recoveredBlobs.keys.has(attachment.storageKey)) return null;
+		return await fetchPageWithRetry(async () => {
+			const download = await client.assets.download({ assetId: asset.id });
 			const resolvedUrl = new URL(download.downloadUrl, sourceHost).toString();
 			const res = await fetch(resolvedUrl);
 			if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
-			const buf = Buffer.from(await res.arrayBuffer());
-			attachmentBlobRows.push({
+			return {
 				storageKey: attachment.storageKey,
 				mimeType: download.mimeType,
-				base64: buf.toString("base64")
-			});
-			blobCount += 1;
-			blobBytes += buf.length;
-		} catch (error) {
+				buf: Buffer.from(await res.arrayBuffer())
+			};
+		}, (attempt, error) => log(`  retrying asset ${asset.id} (attempt ${attempt}/${retries}): ${error instanceof Error ? error.message : String(error)}`), isTransientError, retries);
+	}, async (settled, asset) => {
+		reportBlobProgress();
+		const assetId = asset.id;
+		if (!settled.ok) {
+			const { error } = settled;
 			const message = error instanceof Error ? error.message : String(error);
 			skippedAssets.push(assetId);
 			log(`  WARNING: could not download asset ${assetId}, skipping its blob (${message})`);
+			return;
 		}
-	}
+		if (!settled.value) return;
+		const { storageKey, mimeType, buf } = settled.value;
+		await attachmentBlobs.writeRow({
+			storageKey,
+			mimeType,
+			base64: buf.toString("base64")
+		});
+		blobCount += 1;
+		blobBytes += buf.length;
+	});
 	log(`fetched ${blobCount} attachment blobs (${blobBytes} bytes), skipped ${skippedAssets.length}`);
-	const textBlobRows = [];
-	const seenTextKeys = /* @__PURE__ */ new Set();
-	let textBlobCount = 0;
-	let textBlobBytes = 0;
+	const recoveredTexts = resume ? await recoverCompleteRows(assetTextSpoolPath, "textStorageKey") : {
+		keys: /* @__PURE__ */ new Set(),
+		count: 0,
+		bytes: 0
+	};
+	const textBlobs = new SpooledNdjsonEntry(assetTextSpoolPath, resume);
+	const seenTextKeys = new Set(recoveredTexts.keys);
+	let textBlobCount = recoveredTexts.count;
+	let textBlobBytes = recoveredTexts.bytes;
 	const skippedAssetTexts = [];
-	for (const assetText of tableRows.assetTexts ?? []) {
+	const assetTextRows = tableRows.assetTexts ?? [];
+	if (recoveredTexts.count > 0) log(`  resuming: ${recoveredTexts.count} asset-text blob(s) already downloaded`);
+	const reportTextProgress = throttledProgress(log, () => `  ...asset-text blobs: ${textBlobCount}/${assetTextRows.length} fetched`);
+	await forEachConcurrent(assetTextRows, BLOB_DOWNLOAD_CONCURRENCY, async (assetText) => await fetchPageWithRetry(async () => {
+		const info = await client.dump.exportAssetText({ assetId: assetText.assetId });
+		if (!info.downloadUrl) return null;
+		if (recoveredTexts.keys.has(info.textStorageKey)) return null;
+		const resolvedUrl = new URL(info.downloadUrl, sourceHost).toString();
+		const res = await fetch(resolvedUrl);
+		if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
+		const buf = Buffer.from(await res.arrayBuffer());
+		if (info.textContentHash) {
+			const actual = `sha256:${createHash("sha256").update(buf).digest("hex")}`;
+			if (actual !== info.textContentHash) throw new Error(`content hash mismatch (expected ${info.textContentHash}, downloaded ${actual})`);
+		}
+		return {
+			textStorageKey: info.textStorageKey,
+			buf
+		};
+	}, (attempt, error) => log(`  retrying asset text ${assetText.assetId} (attempt ${attempt}/${retries}): ${error instanceof Error ? error.message : String(error)}`), isTransientError, retries), async (settled, assetText) => {
+		reportTextProgress();
 		const assetId = assetText.assetId;
-		try {
-			const info = await client.dump.exportAssetText({ assetId });
-			if (!info.downloadUrl) continue;
-			if (seenTextKeys.has(info.textStorageKey)) continue;
-			const resolvedUrl = new URL(info.downloadUrl, sourceHost).toString();
-			const res = await fetch(resolvedUrl);
-			if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
-			const buf = Buffer.from(await res.arrayBuffer());
-			if (info.textContentHash) {
-				const actual = `sha256:${createHash("sha256").update(buf).digest("hex")}`;
-				if (actual !== info.textContentHash) throw new Error(`content hash mismatch (expected ${info.textContentHash}, downloaded ${actual})`);
-			}
-			seenTextKeys.add(info.textStorageKey);
-			textBlobRows.push({
-				textStorageKey: info.textStorageKey,
-				base64: buf.toString("base64")
-			});
-			textBlobCount += 1;
-			textBlobBytes += buf.length;
-		} catch (error) {
+		if (!settled.ok) {
+			const { error } = settled;
 			const message = error instanceof Error ? error.message : String(error);
 			skippedAssetTexts.push(assetId);
 			log(`  WARNING: could not download text for asset ${assetId}, skipping its blob (${message})`);
+			return;
 		}
-	}
+		if (!settled.value) return;
+		const { textStorageKey, buf } = settled.value;
+		if (seenTextKeys.has(textStorageKey)) return;
+		seenTextKeys.add(textStorageKey);
+		await textBlobs.writeRow({
+			textStorageKey,
+			base64: buf.toString("base64")
+		});
+		textBlobCount += 1;
+		textBlobBytes += buf.length;
+	});
 	log(`fetched ${textBlobCount} asset-text blobs (${textBlobBytes} bytes), skipped ${skippedAssetTexts.length}`);
-	await writeNdjsonEntry(writer, "tree/attachmentBlobs.ndjson", attachmentBlobRows);
-	await writeNdjsonEntry(writer, "tree/assetTextBlobs.ndjson", textBlobRows);
+	await attachmentBlobs.finish(writer, "tree/attachmentBlobs.ndjson");
+	await textBlobs.finish(writer, "tree/assetTextBlobs.ndjson");
 	for (const table of IMPORT_ORDER) {
 		if (!tables.includes(table)) continue;
 		await writeNdjsonEntry(writer, `tree/${table}.ndjson`, tableRows[table] ?? []);
@@ -3680,10 +4236,24 @@ async function exportFull(options) {
 }
 //#endregion
 //#region src/backup/commands.ts
+/**
+* `backup` and `restore` — the terminal-facing halves of the full-fidelity
+* `.bbdump` archive format. Thin orchestration: drain every dump-eligible table
+* into an archive, or verify an archive and replay it into an empty space.
+*/
 /** Progress is diagnostics, not data — it must never pollute `--output json` on stdout. */
 const reportProgress$1 = (message) => {
 	console.error(message);
 };
+/** Which of this archive's spool files a previous, interrupted run left behind. */
+const findSpoolFiles = async (outFile) => {
+	const present = [];
+	for (const suffix of SPOOL_SUFFIXES) try {
+		await access(`${outFile}${suffix}`);
+		present.push(`${outFile}${suffix}`);
+	} catch {}
+	return present;
+};
 /**
 * Deliberately not implemented: `export` already writes the portable current-state
 * representation as a readable, diffable directory. The two formats stay separate
@@ -3718,7 +4288,11 @@ const runBackup = async (client, options) => {
 	if (options.stateOnly) throw new Error(STATE_ONLY_BACKUP_MESSAGE);
 	const { spaceId } = options;
 	if (!spaceId) throw new Error("No space configured. Pass --space-id <id>, export BUSABASE_SPACE_ID, or run `busabase-cli login`.");
-	reportProgress$1(`Backing up space ${spaceId} → ${options.outFile} (full fidelity, history=${options.includeHistory})`);
+	if (!options.resume) {
+		const orphaned = await findSpoolFiles(options.outFile);
+		if (orphaned.length > 0) reportProgress$1(`  NOTE: found ${orphaned.length} partial file(s) from an interrupted backup (${orphaned.join(", ")}). Re-run with --resume to continue from them; this run will start over and overwrite them.`);
+	}
+	reportProgress$1(`Backing up space ${spaceId} → ${options.outFile} (full fidelity, history=${options.includeHistory}${options.resume ? ", resuming" : ""})`);
 	const manifest = await exportFull({
 		client,
 		outPath: options.outFile,
@@ -3726,6 +4300,8 @@ const runBackup = async (client, options) => {
 		sourceHost: options.baseUrl,
 		includeHistory: options.includeHistory,
 		toolVersion: options.toolVersion,
+		resume: Boolean(options.resume),
+		retries: options.retries,
 		onProgress: (message) => reportProgress$1(`  ${message}`)
 	});
 	const rows = Object.values(manifest.tables).reduce((total, count) => total + count, 0);
@@ -3744,7 +4320,7 @@ const runBackup = async (client, options) => {
 	].join("\n");
 };
 const runRestore = async (client, options) => {
-	if (options.resume) throw new Error("--resume is not implemented yet in this version.");
+	if (options.resume) reportProgress$1("Resuming: rows already present are left alone, and this run will NOT roll back on failure. Only do this to continue THIS archive into THIS space.");
 	reportProgress$1(`Reading ${options.file} …`);
 	const manifest = await verifyArchive(options.file);
 	reportProgress$1(`Archive: fidelity=${manifest.fidelity} space=${manifest.spaceId} exportedAt=${manifest.exportedAt}`);
@@ -3754,6 +4330,7 @@ const runRestore = async (client, options) => {
 		client,
 		archivePath: options.file,
 		sourceSpaceId: manifest.spaceId,
+		resume: Boolean(options.resume),
 		onProgress: (message) => reportProgress$1(`  ${message}`)
 	});
 	if (options.json) return {
@@ -5448,6 +6025,7 @@ const nodeSchema = z.lazy(() => z.object({
 	name: z.string(),
 	description: z.string(),
 	metadata: z.object({ version: z.string().optional() }).catchall(z.unknown()).default({}),
+	settings: nodeSettingsSchema.default({}),
 	explicitVisibility: z.enum([
 		"private",
 		"workspace",
@@ -5531,6 +6109,53 @@ z.object({
 	nodeId: z.string(),
 	metadata: z.record(z.string(), z.unknown())
 });
+/**
+* System settings Busabase itself acts on, per node.
+*
+* A CLOSED object, unlike `metadata`'s `z.record(z.string(), z.unknown())`.
+* That difference is the point: `metadata` is the open bag callers put their
+* own keys in, and its endpoint merges whatever it is handed. Anything the
+* product *reads and acts on* must not live there — `metadata.visibility` had
+* to be pulled out into its own column precisely because the generic endpoint
+* handed a `write`-level actor a door into an ACL input.
+*
+* Adding a key here is a deliberate change to this schema, which is what keeps
+* `PATCH /nodes/{nodeId}/settings` from becoming a second free-form bag.
+*
+* `strictObject`, not `object`: zod's default is to STRIP an unknown key, which
+* would hand a client that misspelled `airappEngine` a 200 and no effect —
+* exactly the silent failure a closed schema exists to prevent. Verified
+* against a running server, where the permissive version returned 200.
+*/
+const nodeSettingsSchema = z.strictObject({ 
+/**
+* Which engine an AirApp runs on, when a human has chosen.
+*
+* `undefined` means "follow the app" — `airapp.json`'s `preferredEngine`
+* decides, or the default does. A value means somebody overrode it in the
+* node settings dialog, and it outranks the manifest from then on. So absence
+* must stay distinguishable from any particular value; `null` clears an
+* override and returns the node to following the app.
+*/
+airappEngine: z.enum([
+	"browser",
+	"local",
+	"remote"
+]).nullish() });
+z.object({
+	nodeId: z.string(),
+	settings: nodeSettingsSchema
+});
+z.object({ nodeId: z.string() });
+z.object({
+	nodeId: z.string(),
+	agentPrompts: customAgentPromptsSchema.nullable()
+});
+z.object({
+	nodeId: z.string(),
+	/** Replaces the whole list — this is not a merge. Send `null` to clear. */
+	agentPrompts: customAgentPromptsSchema.nullable()
+});
 z.object({
 	query: z.string().min(1),
 	limit: z.coerce.number().int().min(1).max(50).optional().default(20)
@@ -5626,6 +6251,55 @@ const commentSubjectTypeSchema = z.enum([
 	"operation",
 	"commit"
 ]);
+/**
+* Who a mention points at. `member` tags a person; `agent` names a launchable
+* Agent target and is what actually starts a session.
+*/
+const commentMentionTargetTypeSchema = z.enum(["member", "agent"]);
+/**
+* Dispatch lifecycle of ONE mention row, before a session exists.
+*
+* `not_applicable` is every member row (a person is not dispatched to).
+* Once `linked`, running/waiting/done/failed belongs to the agent session,
+* never to a second status column here.
+*/
+const commentMentionDispatchStatusSchema = z.enum([
+	"not_applicable",
+	"queued",
+	"linked",
+	"failed"
+]);
+/**
+* One mention as the composer submits it.
+*
+* `start`/`end` are **UTF-16 code unit** offsets into `body` — the same unit
+* `<textarea>` selection APIs and `String.prototype.slice` use, so nothing has
+* to convert at the UI boundary. A label containing an astral-plane character
+* (an emoji in a display name) therefore spans two units per visible glyph;
+* the server rejects a span that would split a surrogate pair.
+*
+* No `label` here on purpose: the client never supplies identity. The server
+* resolves the display name from the member/catalog it already trusts.
+*/
+const commentMentionInputSchema = z.object({
+	type: commentMentionTargetTypeSchema,
+	/** Member/actor id, or launchable agent slug (`claude-acp`, `buda:<agentId>`). */
+	id: z.string().min(1),
+	start: z.number().int().min(0),
+	end: z.number().int().min(0)
+});
+const commentMentionSchema = z.object({
+	id: z.string(),
+	type: commentMentionTargetTypeSchema,
+	targetId: z.string(),
+	/** Server-resolved display name. Falls back to the raw target id. */
+	label: z.string(),
+	start: z.number().int(),
+	end: z.number().int(),
+	dispatchStatus: commentMentionDispatchStatusSchema,
+	sessionId: z.string().nullable(),
+	error: z.string().nullable()
+});
 const commentSchema = z.object({
 	id: z.string(),
 	subjectType: commentSubjectTypeSchema,
@@ -5637,7 +6311,7 @@ const commentSchema = z.object({
 	authorId: z.string(),
 	author: userRefSchema.nullable().optional().default(null),
 	body: z.string(),
-	mentionsAi: z.boolean(),
+	mentions: z.array(commentMentionSchema).default([]),
 	createdAt: z.string(),
 	updatedAt: z.string()
 });
@@ -5726,7 +6400,8 @@ z.object({
 		"change_request.reviewed",
 		"change_request.merged",
 		"change_request.pending_review",
-		"node.metadata_updated"
+		"node.metadata_updated",
+		"node.settings_updated"
 	]),
 	spaceId: z.string(),
 	actorId: z.string(),
@@ -5757,6 +6432,8 @@ const auditActionSchema = z.enum([
 	"asset.text_written",
 	"asset.text_marked_none",
 	"node.metadata_updated",
+	"node.settings_updated",
+	"node.agent_prompts_updated",
 	"node.purged"
 ]);
 z.object({
@@ -5871,7 +6548,12 @@ z.object({
 }).extend({
 	authorId: z.string().optional().default("local-admin"),
 	body: z.string().trim().min(1),
-	mentionsAi: z.boolean().optional().default(false)
+	/**
+	* Structured mentions, owned by the composer. Never inferred from the body by
+	* regex: display names contain spaces and collide with ordinary prose, so
+	* "ask codex about this" must not invoke Codex.
+	*/
+	mentions: z.array(commentMentionInputSchema).optional().default([])
 });
 z.object({ limit: z.coerce.number().int().min(1).max(100).optional().default(50) }).optional().default({ limit: 50 });
 z.object({ status: z.enum(["active", "archived"]).optional().default("active") });
@@ -6605,6 +7287,38 @@ const decodeText = (bytes, filePath) => {
 	if (text.includes("�")) throw new Error(`${filePath} is not valid UTF-8 text.`);
 	return text;
 };
+const AIRAPP_MANIFEST_FILENAME = "airapp.json";
+const PYTHON_RUNTIME_MARKERS = ["requirements.txt", "pyproject.toml"];
+/**
+* Resolve only the lifecycle facts the package format needs to validate.
+* Keep the same explicit -> inferred -> default order as Busabase's runtime
+* descriptor without making busabase-package depend on busabase-core (core
+* already depends on this package).
+*/
+const resolveAirAppPackageLifecycle = (files, slug) => {
+	const paths = new Set(files.map((file) => file.path));
+	const manifestFile = files.find((file) => file.path === AIRAPP_MANIFEST_FILENAME);
+	let manifest = {};
+	if (manifestFile) {
+		let parsed;
+		try {
+			parsed = JSON.parse(decodeText(manifestFile.bytes, AIRAPP_MANIFEST_FILENAME));
+		} catch (error) {
+			throw new Error(`AirApp "${slug}" has an invalid ${AIRAPP_MANIFEST_FILENAME}: ${error.message}`);
+		}
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`AirApp "${slug}" has an invalid ${AIRAPP_MANIFEST_FILENAME}: expected an object.`);
+		manifest = parsed;
+	}
+	const declaredRuntime = manifest.runtime;
+	if (declaredRuntime !== void 0 && declaredRuntime !== "node" && declaredRuntime !== "python") throw new Error(`AirApp "${slug}" declares unknown runtime ${JSON.stringify(declaredRuntime)} in ${AIRAPP_MANIFEST_FILENAME}.`);
+	const runtime = declaredRuntime === "node" || declaredRuntime === "python" ? declaredRuntime : PYTHON_RUNTIME_MARKERS.some((path) => paths.has(path)) ? "python" : "node";
+	const hasCustomCommand = (key) => typeof manifest[key] === "string" && manifest[key].trim().length > 0;
+	return {
+		runtime,
+		usesDefaultInstall: !hasCustomCommand("install"),
+		usesDefaultStart: !hasCustomCommand("start")
+	};
+};
 const parseJsonFile = (files, filePath) => {
 	const bytes = files.get(filePath);
 	if (!bytes) throw new Error(`Missing ${filePath}`);
@@ -6784,7 +7498,10 @@ const readDirNode = (files, dir, slug) => {
 		const ignore = readIgnoreFile(files, dir);
 		const entries = collectSubtree(files, dir).filter((entry) => entry.path !== "_node.json" && entry.path !== ".busabaseignore" && !ignore.ignores(entry.path));
 		assertNoReservedNames(entries.map((entry) => entry.path), `${meta.type} "${slug}"`);
-		if (meta.type === "airapp" && !entries.some((entry) => entry.path === "package.json")) throw new Error(`AirApp "${slug}" has no package.json to install${ignore.isEmpty ? "" : ` — check ${dir}${PACKAGE_AIRAPP_IGNORE}, which must never exclude it`}. Nothing was installed.`);
+		if (meta.type === "airapp") {
+			const lifecycle = resolveAirAppPackageLifecycle(entries, slug);
+			if (lifecycle.runtime === "node" && (lifecycle.usesDefaultInstall || lifecycle.usesDefaultStart) && !entries.some((entry) => entry.path === "package.json")) throw new Error(`AirApp "${slug}" has no package.json required by its default Node lifecycle${ignore.isEmpty ? "" : ` — check ${dir}${PACKAGE_AIRAPP_IGNORE}, which must never exclude it`}. Nothing was installed.`);
+		}
 		return {
 			type: meta.type,
 			slug,
@@ -6981,6 +7698,8 @@ const validateTemplate = (tree) => {
 	else if (airapps.length > 0 || template?.airapp || template?.airapps?.length) errors.push(resolved.error);
 	for (const node of walkNodes(tree.nodes)) {
 		if (!isAirApp(node)) continue;
+		const lifecycle = resolveAirAppPackageLifecycle(node.files, node.slug);
+		if (lifecycle.runtime !== "node" || !lifecycle.usesDefaultStart) continue;
 		const manifestFile = node.files.find((file) => file.path === "package.json");
 		if (!manifestFile) continue;
 		let scripts;
@@ -6990,7 +7709,7 @@ const validateTemplate = (tree) => {
 			errors.push(`AirApp "${node.slug}": package.json is not valid JSON (${error.message}).`);
 			continue;
 		}
-		if (typeof scripts?.dev !== "string") errors.push(`AirApp "${node.slug}": package.json has no \`dev\` script. Busabase starts an AirApp with \`npm run dev\`, so without it the app installs and then never boots.`);
+		if (typeof scripts?.dev !== "string") errors.push(`AirApp "${node.slug}": package.json has no \`dev\` script. This AirApp uses the default Node start command \`npm run dev\`, so without it the app installs and then never boots.`);
 	}
 	if (airapps.length === 0) warnings.push("No AirApp — this template installs data only. Users will see tables, not an app.");
 	if (template?.requires?.airapp && airapps.length === 0) errors.push("template.requires.airapp is true, but content/ contains no AirApp.");
@@ -7495,6 +8214,7 @@ const applyInstall = async (client, plan, options) => {
 		pendingChangeRequests: 0,
 		warnings: [...plan.warnings]
 	};
+	const createdRootNodeIds = [];
 	const fieldIds = /* @__PURE__ */ new Map();
 	const bases = [];
 	const progress = options.onProgress ?? (() => {});
@@ -7514,6 +8234,7 @@ const applyInstall = async (client, plan, options) => {
 				metadata: app?.rootMetadata
 			});
 			state.created.folders++;
+			createdRootNodeIds.push(state.targetFolderNodeId);
 		}
 		await createStructure(client, plan.tree.nodes, state.targetFolderNodeId, options, state, bases, fieldIds, docAssetIds, app);
 		if (app?.rootSkill) {
@@ -7605,8 +8326,16 @@ const applyInstall = async (client, plan, options) => {
 		const created = Object.entries(state.created).filter(([, count]) => count > 0).map(([kind, count]) => `${count} ${kind}`).join(", ");
 		const partial = created ? `Created before failure: ${created}. Target folder: ${plan.targetFolderSlug}.` : "No package resources were created.";
 		const pending = state.pendingChangeRequests ? ` ${state.pendingChangeRequests} ChangeRequest(s) may still be pending.` : "";
+		const rollback = await rollbackPartialInstall(client, {
+			createdRootNodeIds,
+			enabled: options.rollbackOnFailure !== false,
+			installedIntoExistingFolder: Boolean(plan.existingTargetFolderNodeId),
+			anythingCreated: Object.values(state.created).some((count) => count > 0),
+			submittedBy: options.submittedBy ?? "busabase-cli install",
+			progress
+		});
 		const reason = error instanceof Error ? error.message : String(error);
-		const message = `Install stopped during ${phase}. ${partial}${pending} Cause: ${reason}`;
+		const message = `Install stopped during ${phase}. ${partial}${pending}${rollback} Cause: ${reason}`;
 		const details = {
 			phase,
 			targetFolderSlug: plan.targetFolderSlug,
@@ -7621,6 +8350,47 @@ const applyInstall = async (client, plan, options) => {
 	}
 };
 /**
+* Undo a failed install by moving what it created to Trash.
+*
+* Deleting a node takes its whole subtree — Bases, their records, nested
+* folders — so undoing an install is a matter of deleting the roots it made,
+* not walking everything it touched. It moves them to Trash rather than
+* purging: purge refuses a subtree containing a Base (which every real package
+* has), and Trash is reversible, which matters for an automatic action taken
+* while something has already gone wrong.
+*
+* Only ever deletes a target folder THIS install created. Installing into a
+* folder the user already had is reported instead of guessed at: the new nodes
+* sit among the user's own, and there is no reliable way here to tell which
+* were ours. Deleting the wrong thing is far worse than leaving a mess.
+*
+* Best-effort: a rollback runs after a failure, so it can hit the same broken
+* condition. Whatever happens is reported, never thrown — the install error is
+* the one the caller needs.
+*/
+const rollbackPartialInstall = async (client, args) => {
+	if (!args.anythingCreated) return "";
+	if (!args.enabled) return " Left in place (--no-rollback).";
+	if (args.createdRootNodeIds.length === 0) return args.installedIntoExistingFolder ? " Not rolled back: this installed into a folder that already existed, so its new items sit among yours and cannot be told apart safely — remove them by hand." : " Nothing to roll back.";
+	args.progress("Install failed — moving what it created to Trash…");
+	const failures = [];
+	for (const nodeId of args.createdRootNodeIds) try {
+		await client.nodes.createChangeRequest({
+			operations: [{
+				kind: "delete",
+				nodeId
+			}],
+			message: "Roll back a failed install",
+			submittedBy: args.submittedBy,
+			autoMerge: true
+		});
+	} catch (rollbackError) {
+		failures.push(`${nodeId} (${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)})`);
+	}
+	if (failures.length === 0) return " Rolled back: everything it created was moved to Trash.";
+	return ` Rollback incomplete — could not remove ${failures.join("; ")}. Remove them by hand.`;
+};
+/**
 * A property rather than a subclass: the whole point of the rethrow above is to
 * keep the original error's prototype (an `ORPCError`'s `code`/`status`/`data`
 * are what make a permission or quota failure actionable), so the diagnostics
@@ -8129,21 +8899,26 @@ const findSourceNode = (nodes, slugOrId) => {
 const collectPackageTree = async (client, root, options) => {
 	const children = root.type === "folder" ? root.children ?? [] : [root];
 	const { skillSource, rest } = partitionTemplateSkill(children);
-	const nodes = await collectNodes(client, rest, options);
+	const collectOptions = {
+		...options,
+		baseResourceKeys: collectBaseResourceKeys(children)
+	};
+	const nodes = await collectNodes(client, rest, collectOptions);
 	const tree = {
 		manifest: {
 			...options.manifest,
 			format: PACKAGE_FORMAT
 		},
-		nodes: restorePackageSlugs(nodes, children),
-		...skillSource ? { rootSkill: await collectRootSkill(client, skillSource, options) } : {},
-		assets: await collectDocAssets(client, nodes, options)
+		nodes,
+		...skillSource ? { rootSkill: await collectRootSkill(client, skillSource, collectOptions) } : {},
+		assets: await collectDocAssets(client, nodes, collectOptions)
 	};
-	assertSelfContained(tree, options);
+	assertSelfContained(tree, collectOptions);
 	return tree;
 };
 /**
-* Undo the slugs INSTALL chose, restoring the ones the package declared.
+* Undo the slug INSTALL chose for one node, restoring the one the package
+* declared.
 *
 * Install prefixes a template's Base slugs with the target folder (`contacts` →
 * `kelly-crm-contacts`) and records the original as the node's `resourceKey`.
@@ -8153,53 +8928,48 @@ const collectPackageTree = async (client, root, options) => {
 * which is the property that lets a user install a template, adjust it, and
 * publish the result without the names drifting a little further each time.
 *
-* The root folder's own stamp is skipped: its `resourceKey` is the reserved
-* `app-root` marker, not a slug anything should be named after.
-*/
-const restorePackageSlugs = (nodes, sources) => {
-	const renames = /* @__PURE__ */ new Map();
-	const index = (list) => {
+* The app-root stamp is skipped: `resourceKey` is the reserved `app-root`
+* marker there, not a slug anything should be named after.
+*
+* Applied to the ONE node `source` describes — never through a space-wide
+* slug→slug rename table. An earlier version built exactly that table (keyed
+* by each node's *current* slug) and applied it by re-matching slugs across
+* the whole exported tree; that broke the moment two unrelated nodes shared a
+* slug anywhere in the space — observed live: an AirApp installed into a
+* folder auto-named after it end up BOTH called "social-media" pre-restore
+* (the folder, and the app before its own stamp renamed it back to "airapp"),
+* so the app's rename bled onto its own parent folder on export.
+*/
+const restoredNodeSlug = (source) => {
+	const key = source.metadata?.resourceKey;
+	if (typeof key === "string" && key !== "app-root" && key !== source.slug && NODE_SLUG_PATTERN.test(key)) return key;
+	return source.slug;
+};
+/**
+* The other half of slug restoration: a relation field's `targetBaseSlug` (set
+* from `context.baseSlugById` in {@link toPackageField}, itself built by
+* {@link buildIndexes} from each Base's raw current server slug) must resolve
+* to whatever THAT target Base's own node slug gets restored to, or the
+* package would ship a relation pointing at a name it never actually wrote.
+*
+* Keyed by Base id (globally unique, unlike slug — see {@link restoredNodeSlug}'s
+* doc) so `buildIndexes` can look a target base's restored slug up without
+* re-deriving it from a name that might collide with something else in the
+* space.
+*/
+const collectBaseResourceKeys = (sources) => {
+	const byBaseId = /* @__PURE__ */ new Map();
+	const walk = (list) => {
 		for (const source of list) {
-			const key = source.metadata?.resourceKey;
-			if (typeof key === "string" && key !== "app-root" && key !== source.slug && NODE_SLUG_PATTERN.test(key)) renames.set(source.slug, key);
-			if (source.children) index(source.children);
-		}
-	};
-	index(sources);
-	if (renames.size === 0) return [...nodes];
-	const rewriteField = (field) => {
-		const target = field.options.targetBaseSlug;
-		if (!target) return field;
-		const renamed = renames.get(target);
-		return renamed ? {
-			...field,
-			options: {
-				...field.options,
-				targetBaseSlug: renamed
+			if (source.type === "base") {
+				const restored = restoredNodeSlug(source);
+				if (restored !== source.slug) byBaseId.set(source.baseId ?? source.slug, restored);
 			}
-		} : field;
-	};
-	const rewrite = (node) => {
-		const slug = renames.get(node.slug) ?? node.slug;
-		if (node.type === "folder") return {
-			...node,
-			slug,
-			children: node.children.map(rewrite)
-		};
-		if (node.type === "base") return {
-			...node,
-			slug,
-			base: {
-				...node.base,
-				fields: node.base.fields.map(rewriteField)
-			}
-		};
-		return {
-			...node,
-			slug
-		};
+			if (source.children) walk(source.children);
+		}
 	};
-	return nodes.map(rewrite);
+	walk(sources);
+	return byBaseId;
 };
 /**
 * Separate the app's manual from its resources.
@@ -8277,7 +9047,7 @@ const collectNodes = async (client, sources, options) => {
 };
 const collectNode = async (client, source, options) => {
 	const common = {
-		slug: source.slug,
+		slug: restoredNodeSlug(source),
 		name: source.name,
 		description: source.description ?? "",
 		position: source.position
@@ -8314,12 +9084,14 @@ const collectBase = async (client, source, common, options) => {
 	const baseId = source.baseId ?? source.slug;
 	const base = await client.bases.get({ baseId });
 	if (!base) throw new Error(`Base node "${source.slug}" has no Base behind it (looked up ${baseId}). The space may be mid-migration; re-run export.`);
-	const views = await client.bases.listViews({ baseId: base.id });
-	const { baseSlugById, fieldSlugById } = await buildIndexes(client);
+	const allViews = await client.bases.listViews({ baseId: base.id });
+	const views = allViews.filter((view) => view.slug.length > 0);
+	if (views.length !== allViews.length) options.warn(`Base "${common.slug}" has ${allViews.length - views.length} view(s) with no slug — they were dropped (predates the slug requirement; rename it in the UI to keep it).`);
+	const { baseSlugById, fieldSlugById } = await buildIndexes(client, options.baseResourceKeys ?? /* @__PURE__ */ new Map());
 	const fields = [...base.fields].sort((a, b) => a.position - b.position).map((field) => toPackageField(field, {
 		fieldSlugById,
 		baseSlugById,
-		baseSlug: base.slug,
+		baseSlug: common.slug,
 		warn: options.warn
 	}));
 	const records = await collectRecords(client, base.id, base.fields, options);
@@ -8349,12 +9121,12 @@ const collectBase = async (client, source, common, options) => {
 *
 * `bases.list()` already hydrates each base's fields, so one call builds both.
 */
-const buildIndexes = async (client) => {
+const buildIndexes = async (client, baseResourceKeys) => {
 	const bases = await client.bases.list({});
 	const baseSlugById = /* @__PURE__ */ new Map();
 	const fieldSlugById = /* @__PURE__ */ new Map();
 	for (const base of bases) {
-		baseSlugById.set(base.id, base.slug);
+		baseSlugById.set(base.id, baseResourceKeys.get(base.id) ?? base.slug);
 		for (const field of base.fields ?? []) fieldSlugById.set(field.id, field.slug);
 	}
 	return {
@@ -8541,12 +9313,18 @@ const assertSelfContained = (tree, options) => {
 	const packagedRecordKeys = new Set(baseNodes.flatMap((node) => node.type === "base" ? node.records.map((record) => record.key) : []));
 	for (const node of baseNodes) {
 		if (node.type !== "base") continue;
+		for (const field of node.base.fields) {
+			if (field.type !== "attachment" || !field.required) continue;
+			field.required = false;
+			options.warn(`Base "${node.slug}": attachment field "${field.slug}" is required in the source, but ${PACKAGE_FORMAT} never carries attachment values — the field would be empty in every installed record and the install would fail. It is marked NOT required in this package.`);
+		}
 		for (const field of node.base.fields) {
 			const targetBaseSlug = field.options.targetBaseSlug;
 			if (field.type !== "relation" || !targetBaseSlug) continue;
 			if (!packagedBaseSlugs.has(targetBaseSlug)) throw new Error(`Field "${node.slug}.${field.slug}" relates to Base "${targetBaseSlug}", which is outside the subtree being exported. A package must be self-contained — export a subtree that includes both Bases, or remove the field.`);
 		}
 		let dangling = 0;
+		const emptiedRequired = /* @__PURE__ */ new Map();
 		for (const record of node.records) for (const field of node.base.fields) {
 			if (field.type !== "relation") continue;
 			const value = record.fields[field.slug];
@@ -8554,9 +9332,18 @@ const assertSelfContained = (tree, options) => {
 			if (keys.length === 0) continue;
 			const kept = keys.filter((key) => typeof key !== "string" || packagedRecordKeys.has(key));
 			dangling += keys.length - kept.length;
-			if (kept.length !== keys.length) record.fields[field.slug] = kept;
+			if (kept.length !== keys.length) {
+				record.fields[field.slug] = kept;
+				if (kept.length === 0 && field.required) emptiedRequired.set(field.slug, (emptiedRequired.get(field.slug) ?? 0) + 1);
+			}
 		}
 		if (dangling > 0) options.warn(`Base "${node.slug}" has ${dangling} relation value(s) pointing at records outside the exported subtree — they were dropped.`);
+		for (const [slug, count] of emptiedRequired) {
+			const field = node.base.fields.find((candidate) => candidate.slug === slug);
+			if (!field) continue;
+			field.required = false;
+			options.warn(`Base "${node.slug}": relation field "${slug}" is required in the source, but ${count} record(s) point only at records outside the export (typically archived ones, which are never exported). It is marked NOT required in this package so the package can be installed; those records install with that field empty.`);
+		}
 	}
 };
 //#endregion
@@ -8895,15 +9682,59 @@ const renderNodeTree = (nodes, indent) => {
 	return lines;
 };
 /**
-* §4 + §12: without `--auto-merge` an unmerged base has no field ids to patch and no
-* records to link, so passes 2-5 cannot run. Fail fast and say exactly why.
+* A required field the package cannot satisfy for at least one record. The
+* server rejects these — but only once it is already writing records, deep into
+* pass 4 of 5, having created everything before them.
+*
+* Real occurrence: a package whose `content-artifacts` Base declared a REQUIRED
+* attachment field (`busabase-package@1` never carries attachment bytes, so the
+* column is empty in every record) failed with `Invalid field value: 文件 is
+* required` **after creating 2,903 records**. `export` no longer produces such
+* packages, but one written by hand — or exported before that fix — still can,
+* and `install` should say so before touching the target.
 */
-const assertPlanIsApplicable = (plan, autoMerge) => {
+const findUnsatisfiableRequiredFields = (plan) => {
+	const problems = [];
+	for (const node of walkNodes(plan.tree.nodes)) {
+		if (node.type !== "base") continue;
+		for (const field of node.base.fields) {
+			if (!field.required) continue;
+			const missing = node.records.filter((record) => {
+				const value = record.fields[field.slug];
+				if (value === null || value === void 0 || value === "") return true;
+				return Array.isArray(value) && value.length === 0;
+			}).length;
+			if (missing === 0) continue;
+			problems.push(`  • Base "${node.slug}", field "${field.slug}" (${field.type}) is required, but ${missing} of ${node.records.length} record(s) carry no value for it.`);
+		}
+	}
+	return problems;
+};
+/**
+* Everything that would stop this plan from applying, as messages — so a dry
+* run can REPORT them and a real install can throw on them, from one source of
+* truth. Previously the checks lived only inside `assertPlanIsApplicable`,
+* which `--dry-run` returned before ever reaching: a dry run therefore printed
+* a clean-looking plan for a package that could not install at all.
+*/
+const findPlanBlockers = (plan, autoMerge) => {
+	const blockers = [];
 	if (plan.collisions.some((collision) => !collision.renamedTo)) {
 		const list = plan.collisions.filter((collision) => !collision.renamedTo).map((collision) => `  • ${collision.kind} "${collision.slug}" (${collision.path})`).join("\n");
-		throw new Error(`Install would collide with content that already exists:\n${list}\n\nNothing was created. Re-run with --rename to install the colliding items under suffixed slugs (e.g. "-2"), or pick a different --into-folder.`);
+		blockers.push(`Install would collide with content that already exists:\n${list}\n\nNothing was created. Re-run with --rename to install the colliding items under suffixed slugs (e.g. "-2"), or pick a different --into-folder.`);
 	}
-	if (plan.requiresAutoMerge && !autoMerge) throw new Error("This package's records carry relation values, and a relation stores the ids of the records it points at — which only exist once the records are merged. Installing review-first would leave every relation empty.\n\nRe-run with --auto-merge to install it (this trusts the package author: records are created immediately instead of landing as change requests you review first).");
+	if (plan.requiresAutoMerge && !autoMerge) blockers.push("This package's records carry relation values, and a relation stores the ids of the records it points at — which only exist once the records are merged. Installing review-first would leave every relation empty.\n\nRe-run with --auto-merge to install it (this trusts the package author: records are created immediately instead of landing as change requests you review first).");
+	const unsatisfiable = findUnsatisfiableRequiredFields(plan);
+	if (unsatisfiable.length > 0) blockers.push(`This package cannot satisfy its own required fields:\n${unsatisfiable.join("\n")}\n\nThe server rejects these while writing records, partway through the install. Re-export the package (export relaxes fields it cannot fill), or edit the Base definitions in the package to make them optional.`);
+	return blockers;
+};
+/**
+* §4 + §12: without `--auto-merge` an unmerged base has no field ids to patch and no
+* records to link, so passes 2-5 cannot run. Fail fast and say exactly why.
+*/
+const assertPlanIsApplicable = (plan, autoMerge) => {
+	const blockers = findPlanBlockers(plan, autoMerge);
+	if (blockers.length > 0) throw new Error(blockers.join("\n\n"));
 };
 //#endregion
 //#region ../../packages/busabase-package/src/discover.ts
@@ -9541,9 +10372,12 @@ const runInstall = async (client, repoUrl, options) => {
 		installSampleRecords: !options.noSampleRecords
 	});
 	if (options.dryRun) {
-		const report = `${renderPlan(plan)}\n\nDry run — nothing was created.`;
+		const blockers = findPlanBlockers(plan, Boolean(options.autoMerge));
+		const verdict = blockers.length === 0 ? "Dry run — nothing was created. No blockers found." : `Dry run — nothing was created.\n\nThis package would NOT install as-is:\n\n${blockers.join("\n\n")}`;
+		const report = `${renderPlan(plan)}\n\n${verdict}`;
 		return options.json ? {
 			dryRun: true,
+			blockers,
 			...toPlanSummary(plan)
 		} : report;
 	}
@@ -9554,6 +10388,7 @@ const runInstall = async (client, repoUrl, options) => {
 		onProgress: reportProgress,
 		serverUrl: options.serverUrl,
 		installSampleRecords: !options.noSampleRecords,
+		rollbackOnFailure: !options.noRollback,
 		source: {
 			...github ? {
 				repo: `${github.owner}/${github.repo}`,
@@ -9865,67 +10700,6 @@ async function paginateAll(options) {
 	return written;
 }
 //#endregion
-//#region src/retry.ts
-const BASE_DELAY_MS = 500;
-const MAX_DELAY_MS = 2e4;
-const READ_METHODS = /* @__PURE__ */ new Set([
-	"GET",
-	"HEAD",
-	"OPTIONS"
-]);
-const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-const isNetworkError = (error) => error instanceof TypeError || /fetch failed|econnreset|econnrefused|etimedout|socket hang up/i.test(error instanceof Error ? error.message : String(error));
-/** `Retry-After` is either delay-seconds or an HTTP-date; both are legal. */
-function parseRetryAfter(header, now = Date.now()) {
-	if (!header) return void 0;
-	const seconds = Number(header.trim());
-	if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1e3, MAX_DELAY_MS);
-	const at = Date.parse(header);
-	if (Number.isNaN(at)) return void 0;
-	return Math.min(Math.max(at - now, 0), MAX_DELAY_MS);
-}
-/** Whether this outcome is worth another attempt for a request using `method`. */
-function shouldRetry(method, status) {
-	if (status === 429) return true;
-	if (!READ_METHODS.has(method.toUpperCase())) return false;
-	return status === void 0 || status >= 500;
-}
-/**
-* Wrap a fetch so transient failures are retried with exponential backoff.
-* Returns `base` unchanged when `retries` is 0, so the no-retry path adds no
-* wrapper and no behaviour.
-*/
-function withRetry(base, options) {
-	const { retries } = options;
-	if (retries <= 0) return base;
-	const sleep = options.sleep ?? defaultSleep;
-	const notify = options.notify ?? ((message) => console.error(message));
-	const jitter = options.jitter ?? Math.random;
-	return (async (input, init) => {
-		const method = init?.method ?? (input instanceof Request ? input.method : "GET");
-		for (let attempt = 0;; attempt += 1) {
-			let response;
-			let failure;
-			try {
-				response = await base(input, init);
-			} catch (error) {
-				if (!isNetworkError(error)) throw error;
-				failure = error;
-			}
-			const status = response?.status;
-			const last = attempt >= retries;
-			if (!shouldRetry(method, status) || last) {
-				if (response) return response;
-				throw failure;
-			}
-			const backoff = Math.min(BASE_DELAY_MS * 2 ** attempt, MAX_DELAY_MS);
-			const delay = parseRetryAfter(response?.headers.get("retry-after") ?? null) ?? Math.round(backoff * (.5 + jitter() * .5));
-			notify(`[busabase-cli] ${status ? `HTTP ${status}` : "connection failed"} — retrying in ${Math.round(delay / 1e3)}s (attempt ${attempt + 2} of ${retries + 1})`);
-			await sleep(delay);
-		}
-	});
-}
-//#endregion
 //#region src/task-command.ts
 const collect = (value, previous = []) => [...previous, value];
 /** Range-checks before the request goes out, so a cap surfaces as a usage error. */
@@ -10156,14 +10930,22 @@ function resolveConfig(opts) {
 	}));
 	const file = loadDotEnvFile();
 	const baseUrl = opts.baseUrl ?? process.env.BUSABASE_BASE_URL ?? file.BUSABASE_BASE_URL ?? DEFAULT_BASE_URL;
+	const retries = opts.retries ?? DEFAULT_RETRIES;
 	return {
 		baseUrl,
+		/**
+		* The number itself, not just the `fetch` built from it. `backup` retries
+		* at a level this wrapper cannot reach — see `FullExportOptions.retries` —
+		* and has to honour the same flag, or `--retries` silently means nothing
+		* for the one command whose failures cost hours.
+		*/
+		retries,
 		webUrl: process.env.BUSABASE_WEB_URL ?? file.BUSABASE_WEB_URL ?? baseUrl,
 		apiKey: opts.apiKey ?? process.env.BUSABASE_API_KEY ?? file.BUSABASE_API_KEY,
 		spaceId: opts.spaceId ?? process.env.BUSABASE_SPACE_ID ?? file.BUSABASE_SPACE_ID,
 		sourceChannel: "cli",
 		output: opts.output ?? configuredOutput() ?? "text",
-		fetch: withRetry(fetch, { retries: opts.retries ?? DEFAULT_RETRIES })
+		fetch: withRetry(fetch, { retries })
 	};
 }
 /** Enough to ride out a rate limiter or a proxy blip; not enough to hide a real outage. */
@@ -10414,6 +11196,24 @@ async function putTextCommand(client, opts) {
 	});
 }
 /** Wrap a leaf-command handler: resolve config, build the client, render the result. */
+/**
+* Is this a 404 — either "this server has no such route" or "no such node"?
+*
+* Duck-typed rather than an `instanceof ORPCError` check, because this package
+* deliberately depends on no `@orpc/*` package; the SDK builds the error and
+* only its `status` is needed here.
+*
+* Not distinguishing the two 404s is safe for the one thing this gates: a
+* version fallback whose other branch targets the SAME node. An old server
+* answers 404 because the route is missing and the fallback then succeeds; a
+* current server answers 404 because the node does not exist, the fallback
+* asks about the same missing node and 404s too, and the caller still sees a
+* "not found" error. The cost of guessing wrong is one extra request, not a
+* write landing somewhere unintended.
+*/
+function isNotFound(error) {
+	return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
 function runAction(state, handler) {
 	return async (_opts, cmd) => {
 		const opts = cmd.optsWithGlobals();
@@ -10993,7 +11793,7 @@ locale) is reported entry-by-entry and nothing is written. \`--file\`'s
 contents ARE the array to store; this command does not reshape it.
 
 Examples:
-  busabase-cli nodes set-agent-prompts --node-id nod_123 --file prompts.json`).action(runAction(state, (client, opts) => {
+  busabase-cli nodes set-agent-prompts --node-id nod_123 --file prompts.json`).action(runAction(state, async (client, opts) => {
 		const filePath = opts.file;
 		let raw;
 		try {
@@ -11006,10 +11806,19 @@ Examples:
 			const detail = formatIssues(parsed.error.issues);
 			throw new CliOutcomeError("VALIDATION", `Invalid agent prompts in ${filePath}${detail ? ` — ${detail}` : ""}`);
 		}
-		return client.nodes.updateMetadata({
-			nodeId: opts.nodeId,
-			metadata: { agentPrompts: parsed.data }
-		});
+		const nodeId = opts.nodeId;
+		try {
+			return await client.nodes.updateAgentPrompts({
+				nodeId,
+				agentPrompts: parsed.data
+			});
+		} catch (error) {
+			if (!isNotFound(error)) throw error;
+			return await client.nodes.updateMetadata({
+				nodeId,
+				metadata: { agentPrompts: parsed.data }
+			});
+		}
 	}));
 	const bases = program.command("bases").description("Bases (structured tables)");
 	addGlobalFlags(bases.command("list")).description("List Bases in the active space").addOption(new Option("--status <active|archived>", "live Bases (default) or archived ones").choices(["active", "archived"])).action(runAction(state, (client, opts) => client.bases.list({ status: opts.status ?? "active" })));
@@ -11134,7 +11943,7 @@ Examples:
 		startLine: opts.startLine,
 		endLine: opts.endLine
 	})));
-	addGlobalFlags(program.command("install")).description("Install a Busabase package from a GitHub repo or a local directory into this space").argument("<source>", "GitHub repo URL (optionally /tree/<ref>[/<subdir>]), or a local directory / file:// URL written by `busabase-cli export`").option("--into-folder <name>", "target folder slug (default: the package's manifest name)").option("--dry-run", "print the plan (tree, record counts, collisions) and create nothing").option("--auto-merge", "merge the package's records and docs on the spot instead of leaving them as change requests to review — this TRUSTS THE PACKAGE AUTHOR, since skills and AirApps carry code your agents will run (default: review first)").option("--rename", "install colliding items under suffixed slugs (-2, -3, …) instead of failing").option("--skill <name>", "which package to install when the URL is a repository holding several (e.g. busabase/skills)").option("--no-sample-records", "propose a template's sample rows for review instead of merging them (default: merged, so the app is not empty on first open)").addHelpText("after", `
+	addGlobalFlags(program.command("install")).description("Install a Busabase package from a GitHub repo or a local directory into this space").argument("<source>", "GitHub repo URL (optionally /tree/<ref>[/<subdir>]), or a local directory / file:// URL written by `busabase-cli export`").option("--into-folder <name>", "target folder slug (default: the package's manifest name)").option("--dry-run", "print the plan (tree, record counts, collisions) and create nothing").option("--auto-merge", "merge the package's records and docs on the spot instead of leaving them as change requests to review — this TRUSTS THE PACKAGE AUTHOR, since skills and AirApps carry code your agents will run (default: review first)").option("--rename", "install colliding items under suffixed slugs (-2, -3, …) instead of failing").option("--skill <name>", "which package to install when the URL is a repository holding several (e.g. busabase/skills)").option("--no-sample-records", "propose a template's sample rows for review instead of merging them (default: merged, so the app is not empty on first open)").option("--no-rollback", "keep whatever a failed install created (default: it is moved to Trash)").addHelpText("after", `
 The URL's git ref is the version pin — a tag installs that tag's content forever,
 even after the branch moves on. GITHUB_TOKEN is honored for private repos.
 
@@ -11174,6 +11983,7 @@ field with nothing linked yet does not trigger this.`).action(runArgAction(state
 		rename: Boolean(opts.rename),
 		skill: opts.skill,
 		noSampleRecords: opts.sampleRecords === false,
+		noRollback: opts.rollback === false,
 		json: config.output === "json",
 		githubToken: process.env.GITHUB_TOKEN,
 		serverUrl: config.baseUrl
@@ -11236,7 +12046,7 @@ and as something \`busabase-cli install\` can install.`).action(runArgAction(sta
 		json: config.output === "json",
 		baseUrl: config.baseUrl
 	})));
-	addGlobalFlags(program.command("backup")).description("Back up the active space to a full-fidelity .bbdump archive").option("-o, --out-file <file>", "output archive path", "space.bbdump").option("--no-history", "full-fidelity rows, but omit the history tables (commits, change requests, operations, comments, reviews, audit events)").option("--state-only", "superseded by `busabase-cli export` — see the error text").addHelpText("after", `
+	addGlobalFlags(program.command("backup")).description("Back up the active space to a full-fidelity .bbdump archive").option("-o, --out-file <file>", "output archive path", "space.bbdump").option("--no-history", "drop finished change requests, reviews, comments and audit events (unfinished work is kept)").option("--state-only", "superseded by `busabase-cli export` — see the error text").option("--resume", "continue an interrupted backup, reusing the attachment bytes it already downloaded").addHelpText("after", `
 A backup is full fidelity: raw rows with their original ids, every doc body, and
 every attachment's bytes, in one integrity-checked archive. Vault items and
 webhook signing secrets are never written to it.
@@ -11244,19 +12054,27 @@ webhook signing secrets are never written to it.
 Examples:
   busabase-cli backup                                        # → ./space.bbdump
   busabase-cli backup -o ./backups/acme-2026-07-19.bbdump
-  busabase-cli backup --no-history                           # smaller: current state only
+  busabase-cli backup --no-history                           # current state + unfinished work
+
+\`--no-history\` still restores completely: every record, field value, file and
+permission is there. What it leaves out is the paper trail — change requests
+that are already finished, their reviews and comments, and the audit log of who
+did what when. Change requests still in review (or approved but unmerged) are
+KEPT, because those are unfinished work rather than history.
 
 To hand content to someone else rather than back it up, use \`busabase-cli export\`,
 which writes a readable, diffable package directory you can push to GitHub.`).action(runAction(state, (client, opts, config) => runBackup(client, {
 		outFile: opts.outFile,
 		includeHistory: opts.history !== false,
+		resume: Boolean(opts.resume),
 		stateOnly: Boolean(opts.stateOnly),
 		json: config.output === "json",
 		baseUrl: config.baseUrl,
 		spaceId: config.spaceId,
+		retries: config.retries,
 		toolVersion: pkgVersion()
 	})));
-	addGlobalFlags(program.command("restore")).description("Restore a .bbdump archive into an EMPTY space, preserving original ids").argument("<file>", "path to the .bbdump archive").option("--resume", "resume a previously interrupted restore (not yet implemented)").option("--into-folder <name>", "state-only archives only — see the error text").addHelpText("after", `
+	addGlobalFlags(program.command("restore")).description("Restore a .bbdump archive into an EMPTY space, preserving original ids").argument("<file>", "path to the .bbdump archive").option("--resume", "continue a restore whose process was killed partway through (same archive, same space)").option("--into-folder <name>", "state-only archives only — see the error text").addHelpText("after", `
 The archive's checksum is verified before a single row is written, and the target
 space must be EMPTY — a restore replays original ids, so it cannot merge into a
 space that already holds content. Those ids are also unique across the whole