@camstack/system 1.2.179 → 1.2.181

package/dist/builtins/backup-orchestrator/backup-orchestrator.addon.mjs

@@ -1,4 +1,4 @@
-import { Ft as BaseAddon, j as backupCapability, sn as EventCategory } from "../../dist-L_39vRmH.mjs";
+import { Ft as BaseAddon, j as backupCapability, sn as EventCategory } from "../../dist-DbnNk4Lw.mjs";
 import { randomBytes, randomUUID } from "node:crypto";
 import { Buffer as Buffer$1 } from "buffer";
 import * as fsp from "node:fs/promises";
@@ -9,7 +9,7 @@ import * as fs from "node:fs";
 import Kt from "node:fs";
 import * as zlib from "node:zlib";
 import { EventEmitter } from "node:events";
-import As from "node:stream";
+import As, { Transform } from "node:stream";
 import { StringDecoder } from "node:string_decoder";
 import I from "fs";
 import qs, { dirname as dirname$1, parse } from "path";
@@ -17,6 +17,7 @@ import * as Ms from "zlib";
 import Jr from "zlib";
 import Pi from "assert";
 import $r, { EventEmitter as EventEmitter$1 } from "events";
+import { pipeline } from "node:stream/promises";
 import no from "node:assert";
 //#region node_modules/tar/dist/esm/index.min.js
 var Mr = Object.defineProperty;
@@ -2989,13 +2990,32 @@ var Ro = (s) => {
 //#endregion
 //#region src/builtins/system-backup/system-backup.service.ts
 /**
+* Thrown when an archive build (or a backup run driving one) is
+* stopped via its `AbortSignal`. Callers use `instanceof` to tell a
+* deliberate operator cancel from a real failure — a cancelled run is
+* an outcome, not an error to alert on. (D342)
+*/
+var BackupCancelledError = class extends Error {
+	constructor(message = "backup run cancelled") {
+		super(message);
+		this.name = "BackupCancelledError";
+	}
+};
+/** Throw `BackupCancelledError` when the signal has fired. */
+function throwIfCancelled(signal) {
+	if (signal?.aborted) throw new BackupCancelledError();
+}
+/**
 * Default set of paths considered part of a "system backup". Includes
 * everything that isn't pure backend code — config, sqlite, addons
 * (runtime overlay), addons-data (per-addon private dir), TLS certs,
 * auto-update marker.
 *
-* Excluded by default: recordings/, media/, models/, logs/, cache/
-* (too large or fully recreatable).
+* Anything not listed is excluded by omission — recordings/, media/,
+* models/, logs/, cache/ (too large or fully recreatable). Note this
+* covers only TOP-LEVEL trees: bulk nested INSIDE a listed location
+* is excluded via `DEFAULT_BACKUP_EXCLUDES` + the node_modules rule
+* below, enforced in the walk and the tar filter alike.
 */
 var DEFAULT_BACKUP_LOCATIONS = [
 	"config.yaml",
@@ -3004,6 +3024,40 @@ var DEFAULT_BACKUP_LOCATIONS = [
 	"tls",
 	"auto-update.json"
 ];
+/**
+* Subtrees never captured by a system backup even though they live
+* under a `DEFAULT_BACKUP_LOCATIONS` entry. Paths are dataDir-relative
+* prefixes. Two lessons from the live hub (2026-09-04, D-record
+* "backup excludes"):
+*
+* - `addons-data/backup-orchestrator/staging` — the orchestrator's
+*   LEGACY staging dir (now `<dataDir>/backup-staging`, outside every
+*   location). Before Jul 28 every archive nested all previous
+*   archives (175M → 503M → 4.5G); leaked files from that era must
+*   never be re-swept into new backups.
+* - `addons-data/recorder/exports` — operator-exported clips (8.4 GB
+*   on the hub). Media, not system state; a restore has no use for it.
+*/
+var DEFAULT_BACKUP_EXCLUDES = ["addons-data/backup-orchestrator/staging", "addons-data/recorder/exports"];
+/**
+* Directory name excluded wherever it appears in the tree.
+* `AddonInstaller` materialises runtime deps under
+* `addons/@camstack/<addon>/node_modules` (~196 MB on the hub); only
+* built `dist` + package.json + assets are restore-worthy — deps are
+* reinstalled from npm on demand. node_modules is NEVER archived.
+*/
+var EXCLUDED_DIR_NAME = "node_modules";
+/**
+* True when a dataDir-relative path must be omitted from archives,
+* manifests and location stats. Accepts tar-style paths (`./` prefix,
+* trailing `/`) and backslash separators.
+*/
+function isExcludedFromBackup(relPath) {
+	const norm = relPath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+	if (norm.length === 0) return false;
+	if (norm.split("/").includes(EXCLUDED_DIR_NAME)) return true;
+	return DEFAULT_BACKUP_EXCLUDES.some((prefix) => norm === prefix || norm.startsWith(`${prefix}/`));
+}
 /** Path of the manifest file embedded inside every archive. */
 var ARCHIVE_MANIFEST_NAME = ".camstack-backup-manifest.json";
 var DEFAULT_STAT_CACHE_TTL_MS = 6e4;
@@ -3056,7 +3110,7 @@ var SystemBackupService = class {
 			fileCount: 0,
 			present: false
 		};
-		const walked = await walkAbs(abs, abs);
+		const walked = await walkAbs(abs, abs, this.exclusionPredicate());
 		return {
 			name: loc,
 			sizeBytes: walked.reduce((acc, e) => acc + e.sizeBytes, 0),
@@ -3076,8 +3130,20 @@ var SystemBackupService = class {
 	*
 	* Locations that don't exist are silently skipped. Throws if zero
 	* locations would be included.
+	*
+	* Cancellation: `signal` aborts the build IN FLIGHT — the manifest
+	* walk checks it per filesystem node and the tar phase runs through
+	* `stream.pipeline(..., { signal })`, which destroys the pack and
+	* the file sink immediately. On abort the half-written archive is
+	* deleted here (never left for the caller to remember) and the call
+	* rejects with {@link BackupCancelledError}. (D342)
+	*
+	* Progress: `onArchiveBytes` receives the cumulative compressed
+	* bytes written to `archivePath` — the live "how large has staging
+	* grown" counter `backup.listRuns` exposes.
 	*/
 	async createArchive(opts) {
+		throwIfCancelled(opts.signal);
 		const requested = opts.locations ?? DEFAULT_BACKUP_LOCATIONS;
 		const present = [];
 		for (const loc of requested) {
@@ -3090,9 +3156,10 @@ var SystemBackupService = class {
 		await this.checkpointDatabasesUnder(present);
 		const entries = [];
 		for (const loc of present) {
+			throwIfCancelled(opts.signal);
 			const abs = path$1.join(this.dataDir, loc);
 			const stat = await fsp.stat(abs);
-			if (stat.isDirectory()) for (const e of await walkAbs(abs, this.dataDir)) entries.push(e);
+			if (stat.isDirectory()) for (const e of await walkAbs(abs, this.dataDir, this.exclusionPredicate(), opts.signal)) entries.push(e);
 			else entries.push(toArchiveEntry(abs, this.dataDir, stat));
 		}
 		const manifest = {
@@ -3118,18 +3185,28 @@ var SystemBackupService = class {
 			const stagingRel = path$1.relative(this.dataDir, path$1.dirname(opts.archivePath));
 			const excludePrefix = stagingRel && !stagingRel.startsWith("..") && !path$1.isAbsolute(stagingRel) ? stagingRel : null;
 			try {
-				await Kn({
-					file: opts.archivePath,
+				const pack = Kn({
 					gzip: true,
 					cwd: this.dataDir,
 					follow: true,
 					portable: true,
 					filter: (entryPath) => {
-						if (!excludePrefix) return true;
 						const norm = entryPath.replace(/^\.\//, "").replace(/\/+$/, "");
+						if (isExcludedFromBackup(norm)) return false;
+						if (!excludePrefix) return true;
 						return norm !== excludePrefix && !norm.startsWith(`${excludePrefix}/`);
 					}
 				}, [ARCHIVE_MANIFEST_NAME, ...present]);
+				const sink = fs.createWriteStream(opts.archivePath);
+				try {
+					await pipeline(pack, byteCountingPassthrough(opts.onArchiveBytes), sink, opts.signal ? { signal: opts.signal } : {});
+				} catch (err) {
+					try {
+						fs.rmSync(opts.archivePath, { force: true });
+					} catch {}
+					if (opts.signal?.aborted) throw new BackupCancelledError();
+					throw err;
+				}
 			} finally {
 				try {
 					fs.rmSync(stagedInDataDir, { force: true });
@@ -3163,7 +3240,7 @@ var SystemBackupService = class {
 	*/
 	async checkpointDatabasesUnder(locations) {
 		const dbPaths = /* @__PURE__ */ new Set();
-		for (const loc of locations) await collectWalDatabases(path$1.isAbsolute(loc) ? loc : path$1.join(this.dataDir, loc), dbPaths);
+		for (const loc of locations) await collectWalDatabases(path$1.isAbsolute(loc) ? loc : path$1.join(this.dataDir, loc), dbPaths, this.exclusionPredicate());
 		if (dbPaths.size === 0) return;
 		let Database;
 		try {
@@ -3308,6 +3385,15 @@ var SystemBackupService = class {
 	getRestoreMarkerPath() {
 		return path$1.join(this.dataDir, ".pending-restore.json");
 	}
+	/**
+	* Absolute-path form of {@link isExcludedFromBackup}, anchored on
+	* this service's dataDir. Shared by the manifest walk, the location
+	* stats and the WAL-checkpoint scan so all three agree with the tar
+	* filter about what a backup contains.
+	*/
+	exclusionPredicate() {
+		return (abs) => isExcludedFromBackup(path$1.relative(this.dataDir, abs));
+	}
 };
 /**
 * Recursively collect every SQLite database under `abs` that is in WAL
@@ -3316,7 +3402,8 @@ var SystemBackupService = class {
 * (unreadable dir, broken symlink) are skipped silently — this feeds a
 * best-effort step.
 */
-async function collectWalDatabases(abs, out) {
+async function collectWalDatabases(abs, out, shouldSkip) {
+	if (shouldSkip?.(abs)) return;
 	let stat;
 	try {
 		stat = await fsp.stat(abs);
@@ -3330,7 +3417,7 @@ async function collectWalDatabases(abs, out) {
 		} catch {
 			return;
 		}
-		for (const child of children) await collectWalDatabases(path$1.join(abs, child), out);
+		for (const child of children) await collectWalDatabases(path$1.join(abs, child), out, shouldSkip);
 		return;
 	}
 	if (abs.endsWith("-wal")) {
@@ -3344,12 +3431,14 @@ async function collectWalDatabases(abs, out) {
 * path. Symlinks are dereferenced (matches the `follow: true` flag we
 * pass to tar.create).
 */
-async function walkAbs(absRoot, dataDir) {
+async function walkAbs(absRoot, dataDir, shouldSkip, signal) {
 	const out = [];
-	await walkRec(absRoot, dataDir, out);
+	await walkRec(absRoot, dataDir, out, shouldSkip, signal);
 	return out;
 }
-async function walkRec(abs, dataDir, out) {
+async function walkRec(abs, dataDir, out, shouldSkip, signal) {
+	throwIfCancelled(signal);
+	if (shouldSkip?.(abs)) return;
 	let stat;
 	try {
 		stat = await fsp.stat(abs);
@@ -3364,9 +3453,22 @@ async function walkRec(abs, dataDir, out) {
 		} catch {
 			return;
 		}
-		for (const child of children) await walkRec(path$1.join(abs, child), dataDir, out);
+		for (const child of children) await walkRec(path$1.join(abs, child), dataDir, out, shouldSkip, signal);
 	}
 }
+/**
+* Pass-through transform that reports the CUMULATIVE bytes flowed so
+* far. Sits between the tar pack and the file sink so the caller's
+* progress counter tracks the compressed archive as it grows on disk.
+*/
+function byteCountingPassthrough(onBytes) {
+	let total = 0;
+	return new Transform({ transform(chunk, _encoding, callback) {
+		if (Buffer.isBuffer(chunk)) total += chunk.byteLength;
+		onBytes?.(total);
+		callback(null, chunk);
+	} });
+}
 function toArchiveEntry(abs, dataDir, stat) {
 	const rel = path$1.relative(dataDir, abs).replace(/\\/g, "/");
 	const kind = stat.isDirectory() ? "dir" : stat.isSymbolicLink() ? "symlink" : "file";
@@ -4586,6 +4688,257 @@ var LocationManifestLock = class {
 	}
 };
 //#endregion
+//#region src/builtins/backup-orchestrator/run-queue.ts
+/**
+* Backup run queue + per-run tracking (D342).
+*
+* Why a GLOBAL queue (concurrency 1), not per-destination: every run
+* walks the same `<nodeDataDir>` source tree and stages its tar.gz on
+* the same disk. On 2026-09-04 two schedule ticks built two multi-GB
+* archives concurrently — staging went 5.1 GB → 18 GB in ~12 minutes
+* with host load 62, and each run archived the other's growing tar
+* (pre-D338 staging placement). A per-destination lock would still
+* allow two concurrent walks of the same tree and two staged archives;
+* the destination write is the CHEAP half. One run at a time bounds
+* peak staging disk to a single archive and the walk cost to one
+* traversal.
+*
+* This subsumes the earlier single-flight `buildLock`
+* (`LocationManifestLock.run('archive-build', …)`): that lock
+* serialised builds but was invisible (nothing reported a waiting
+* run), unjoinable and uncancellable. The queue is the one
+* serialisation authority for archive builds — do not reintroduce a
+* second lock around the executor.
+*
+* Every run is OBSERVABLE while it exists: id, state, phase, byte
+* counters, per-destination outcome. The registry keeps queued +
+* active + a bounded tail of finished runs so `backup.listRuns` can
+* answer "what is running, how far along, how big" without `du`.
+*/
+/** Finished runs kept for `listRuns` history. Older ones are dropped. */
+var DEFAULT_MAX_FINISHED = 20;
+/**
+* FIFO queue with concurrency 1. `submit` never starts a second
+* executor while one is in flight; an identical request already
+* WAITING (same destinations/locations/label/retention) is joined
+* instead of queued twice — two schedule ticks due on the same minute
+* produce one run, not two.
+*/
+var BackupRunQueue = class {
+	executor;
+	runs = /* @__PURE__ */ new Map();
+	pending = [];
+	finished = [];
+	activeId = null;
+	maxFinished;
+	now;
+	constructor(executor, opts) {
+		this.executor = executor;
+		this.maxFinished = opts?.maxFinished ?? DEFAULT_MAX_FINISHED;
+		this.now = opts?.now ?? Date.now;
+	}
+	submit(request) {
+		const signature = requestSignature(request);
+		const busy = this.activeId !== null || this.pending.length > 0;
+		for (const id of this.pending) {
+			const existing = this.runs.get(id);
+			if (existing && existing.signature === signature) return {
+				runId: id,
+				queued: true,
+				joined: true,
+				result: existing.resultPromise
+			};
+		}
+		const record = this.createRecord(request, signature);
+		this.runs.set(record.snapshot.id, record);
+		this.pending.push(record.snapshot.id);
+		this.pump();
+		return {
+			runId: record.snapshot.id,
+			queued: busy,
+			joined: false,
+			result: record.resultPromise
+		};
+	}
+	/**
+	* Cancel a run. Queued: removed before it ever starts (its result
+	* rejects `BackupCancelledError`). Running: the abort signal fires —
+	* the executor's tar/upload streams stop and its cleanup runs.
+	* Unknown or already terminal: `false`.
+	*/
+	cancel(runId) {
+		const record = this.runs.get(runId);
+		if (!record) return false;
+		if (record.snapshot.state === "queued") {
+			const idx = this.pending.indexOf(runId);
+			if (idx >= 0) this.pending.splice(idx, 1);
+			this.finish(record, "cancelled");
+			record.rejectResult(new BackupCancelledError(`backup run ${runId} cancelled while queued`));
+			return true;
+		}
+		if (record.snapshot.state === "running") {
+			record.controller.abort();
+			return true;
+		}
+		return false;
+	}
+	/**
+	* EXECUTION order, not timestamp order: the running run first, then
+	* every queued run in the exact order the pump will start them (each
+	* stamped with `queuePosition`, 1 = next), then the bounded finished
+	* history newest-first. The queued section is read straight off
+	* `this.pending` — a consumer sorting by `requestedAt` descending
+	* would put the run that starts NEXT at the BOTTOM, which is
+	* backwards exactly when the queue matters (more than one waiter).
+	*/
+	listRuns() {
+		const running = [];
+		const finished = [];
+		for (const record of this.runs.values()) {
+			const snap = record.snapshot;
+			if (snap.state === "running") running.push(snap);
+			else if (snap.state !== "queued") finished.push(snap);
+		}
+		const queued = [];
+		for (const [index, id] of this.pending.entries()) {
+			const record = this.runs.get(id);
+			if (record) queued.push({
+				...record.snapshot,
+				queuePosition: index + 1
+			});
+		}
+		finished.sort((a, b) => b.requestedAt - a.requestedAt);
+		return [
+			...running,
+			...queued,
+			...finished
+		];
+	}
+	getRun(runId) {
+		const record = this.runs.get(runId);
+		if (!record) return void 0;
+		const pendingIndex = this.pending.indexOf(runId);
+		return pendingIndex >= 0 ? {
+			...record.snapshot,
+			queuePosition: pendingIndex + 1
+		} : record.snapshot;
+	}
+	createRecord(request, signature) {
+		let resolveResult;
+		let rejectResult;
+		const resultPromise = new Promise((res, rej) => {
+			resolveResult = res;
+			rejectResult = rej;
+		});
+		resultPromise.catch(() => void 0);
+		return {
+			snapshot: {
+				id: randomUUID(),
+				state: "queued",
+				phase: "queued",
+				destinationIds: request.destinations ?? [],
+				...request.label !== void 0 ? { label: request.label } : {},
+				requestedAt: this.now(),
+				stagedBytes: 0,
+				uploadedBytes: 0,
+				completedDestinationIds: [],
+				failedDestinationIds: []
+			},
+			request,
+			signature,
+			controller: new AbortController(),
+			resultPromise,
+			resolveResult,
+			rejectResult
+		};
+	}
+	pump() {
+		if (this.activeId !== null) return;
+		const nextId = this.pending.shift();
+		if (nextId === void 0) return;
+		const record = this.runs.get(nextId);
+		if (!record) {
+			this.pump();
+			return;
+		}
+		this.activeId = nextId;
+		this.patch(record, {
+			state: "running",
+			phase: "building",
+			startedAt: this.now()
+		});
+		this.execute(record);
+	}
+	async execute(record) {
+		const progress = this.progressFor(record);
+		try {
+			const value = await this.executor(record.request, record.controller.signal, progress);
+			this.finish(record, record.controller.signal.aborted ? "cancelled" : "succeeded");
+			record.resolveResult(value);
+		} catch (err) {
+			if (err instanceof BackupCancelledError || record.controller.signal.aborted) {
+				this.finish(record, "cancelled");
+				record.rejectResult(err instanceof BackupCancelledError ? err : new BackupCancelledError());
+			} else {
+				this.finish(record, "failed", err instanceof Error ? err.message : String(err));
+				record.rejectResult(err);
+			}
+		} finally {
+			this.activeId = null;
+			this.pump();
+		}
+	}
+	progressFor(record) {
+		return {
+			setPhase: (phase) => this.patch(record, { phase }),
+			setDestinations: (ids) => this.patch(record, { destinationIds: [...ids] }),
+			setStagedBytes: (bytes) => this.patch(record, { stagedBytes: bytes }),
+			setArchiveSize: (bytes) => this.patch(record, { archiveSizeBytes: bytes }),
+			setUploadedBytes: (bytes) => this.patch(record, { uploadedBytes: bytes }),
+			destinationCompleted: (id) => this.patch(record, {
+				completedDestinationIds: [...record.snapshot.completedDestinationIds, id],
+				uploadedBytes: 0
+			}),
+			destinationFailed: (id) => this.patch(record, {
+				failedDestinationIds: [...record.snapshot.failedDestinationIds, id],
+				uploadedBytes: 0
+			})
+		};
+	}
+	patch(record, patch) {
+		record.snapshot = {
+			...record.snapshot,
+			...patch
+		};
+	}
+	finish(record, state, error) {
+		this.patch(record, {
+			state,
+			phase: "done",
+			finishedAt: this.now(),
+			...error !== void 0 ? { error } : {}
+		});
+		this.finished.push(record.snapshot.id);
+		while (this.finished.length > this.maxFinished) {
+			const evicted = this.finished.shift();
+			if (evicted !== void 0) this.runs.delete(evicted);
+		}
+	}
+};
+/**
+* Canonical signature for join-detection. Order-normalised so
+* `{ destinations: [a, b] }` and `{ destinations: [b, a] }` — the same
+* fan-out set — coalesce.
+*/
+function requestSignature(request) {
+	return JSON.stringify({
+		destinations: [...request.destinations ?? []].toSorted(),
+		locations: [...request.locations ?? []].toSorted(),
+		label: request.label ?? null,
+		retentionCount: request.retentionCount ?? null
+	});
+}
+//#endregion
 //#region src/builtins/backup-orchestrator/schedule-store.ts
 /**
 * @durable class=config owner=backup-orchestrator
@@ -4762,6 +5115,107 @@ function mapRowToSchedule(row) {
 	};
 }
 //#endregion
+//#region src/builtins/backup-orchestrator/staging-paths.ts
+/** Basename of the staging dir under the node data root. */
+var STAGING_DIR_NAME = "backup-staging";
+/** Canonical staging dir for a node data root. */
+function resolveStagingDir(nodeDataDir) {
+	return path$1.join(nodeDataDir, STAGING_DIR_NAME);
+}
+/**
+* Delete every top-level entry of `stagingDir` except those whose
+* resolved path appears in `keepPaths`. Per-entry failures are logged
+* and skipped — a locked file must not abort the sweep. A missing
+* staging dir is a clean no-op.
+*/
+async function sweepStagingDir(input) {
+	const keep = new Set(input.keepPaths.map((p) => path$1.resolve(p)));
+	let entries;
+	try {
+		entries = await fsp.readdir(input.stagingDir);
+	} catch {
+		return {
+			removedCount: 0,
+			freedBytes: 0,
+			keptCount: 0
+		};
+	}
+	let removedCount = 0;
+	let freedBytes = 0;
+	let keptCount = 0;
+	for (const name of entries) {
+		const abs = path$1.join(input.stagingDir, name);
+		if (keep.has(path$1.resolve(abs))) {
+			keptCount++;
+			continue;
+		}
+		try {
+			const footprint = await measureDirectoryFootprint(abs);
+			await fsp.rm(abs, {
+				recursive: true,
+				force: true
+			});
+			removedCount++;
+			freedBytes += footprint.totalBytes;
+		} catch (err) {
+			input.logger.warn("backup staging sweep: entry removal failed — skipping", { meta: {
+				path: abs,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
+	return {
+		removedCount,
+		freedBytes,
+		keptCount
+	};
+}
+/**
+* Recursive size + file count of a path (file or directory). Absent
+* path → `present: false` with zeros. Used by the sweep to report
+* reclaimed bytes and by the orchestrator to surface the legacy
+* staging dir's footprint without touching it.
+*/
+async function measureDirectoryFootprint(dir) {
+	let stat;
+	try {
+		stat = await fsp.stat(dir);
+	} catch {
+		return {
+			present: false,
+			totalBytes: 0,
+			fileCount: 0
+		};
+	}
+	if (!stat.isDirectory()) return {
+		present: true,
+		totalBytes: stat.size,
+		fileCount: 1
+	};
+	let totalBytes = 0;
+	let fileCount = 0;
+	let children;
+	try {
+		children = await fsp.readdir(dir);
+	} catch {
+		return {
+			present: true,
+			totalBytes: 0,
+			fileCount: 0
+		};
+	}
+	for (const child of children) {
+		const nested = await measureDirectoryFootprint(path$1.join(dir, child));
+		totalBytes += nested.totalBytes;
+		fileCount += nested.fileCount;
+	}
+	return {
+		present: true,
+		totalBytes,
+		fileCount
+	};
+}
+//#endregion
 //#region src/builtins/backup-orchestrator/write-targets.ts
 /**
 * Pick the destinations an archive may be fanned out to.
@@ -4806,8 +5260,9 @@ function selectBackupTargets(input) {
 * that list with the `backup_destination_policies` table to surface
 * `enabled` / `retentionCount` / `label`. The actual archive bytes
 * travel through `api.storage.beginUpload` / `writeChunk` /
-* `finalizeUpload`, with the staging archive built into the addon's
-* private `ctx.dataDir/staging` dir.
+* `finalizeUpload`, with the staging archive built into
+* `<nodeDataDir>/backup-staging` (outside every backed-up location —
+* see staging-paths.ts).
 */
 /**
 * Hardcoded seed for newly-discovered `backups` locations. Operators
@@ -4859,10 +5314,12 @@ var BackupOrchestratorAddon = class extends BaseAddon {
 	/**
 	* Transient build buffer for archive fan-out. The tar is built here
 	* ONCE, streamed to every destination via the storage cap's chunked
-	* upload, then removed. Lives in the addon's private `ctx.dataDir`
-	* (never `api.storage.resolve`, per the AddonContext contract) — a
-	* `cache` storage location is never declared, so resolving one threw
-	* and aborted every run before a byte was written.
+	* upload, then removed. Lives at `<nodeDataDir>/backup-staging` —
+	* OUTSIDE every backed-up location, so a backup can never contain a
+	* backup (the old `ctx.dataDir/staging` sat inside `addons-data` and
+	* compounded 175M → 4.5G before Jul 28), and distinct from
+	* `<nodeDataDir>/backups` where the default `backups` destination
+	* seeds when `CAMSTACK_BACKUP_ROOT` is unset. See staging-paths.ts.
 	*/
 	stagingDir = "";
 	scheduleTimer = null;
@@ -4874,13 +5331,24 @@ var BackupOrchestratorAddon = class extends BaseAddon {
 	*/
 	scheduleBaselineAt = Date.now();
 	manifestLock = new LocationManifestLock();
+	/**
+	* Global execution queue — at most ONE archive build at a time,
+	* cluster-node-wide (D342). Replaces the earlier invisible
+	* single-flight `buildLock`: same serialisation guarantee (two
+	* schedules due one tick apart built 8.2 GB + 3.7 GB side by side on
+	* the hub, 2026-09-04), but every run is now observable via
+	* `listRuns`, joinable when identical, and cancellable mid-stream.
+	*/
+	runQueue = null;
 	constructor() {
 		super({});
 	}
 	async onInitialize() {
 		this.dataDir = this.ctx.nodeDataDir;
-		this.stagingDir = path$1.join(this.ctx.dataDir, "staging");
+		this.stagingDir = resolveStagingDir(this.ctx.nodeDataDir);
 		this.systemBackup = new SystemBackupService(this.dataDir, this.ctx.logger);
+		this.runQueue = new BackupRunQueue((request, signal, progress) => this.runBackupBuild(request, signal, progress));
+		await this.cleanStagingArea();
 		this.policies = this.resolvePolicyService();
 		if (this.policies) try {
 			await this.policies.initialize();
@@ -4900,6 +5368,8 @@ var BackupOrchestratorAddon = class extends BaseAddon {
 			list: () => this.aggregatedList(),
 			listLocations: () => this.systemBackup.statLocations(),
 			trigger: (input) => this.triggerBackup(input),
+			listRuns: () => this.listRuns(),
+			cancel: (input) => this.cancelRun(input),
 			getEntries: (input) => this.getEntries(input),
 			restore: (input) => this.scheduleRestore(input),
 			delete: (input) => this.deleteArchive(input),
@@ -4922,6 +5392,10 @@ var BackupOrchestratorAddon = class extends BaseAddon {
 	}
 	async onShutdown() {
 		this.stopScheduleTimer();
+		if (this.runQueue) {
+			for (const run of this.runQueue.listRuns()) if (run.state === "queued" || run.state === "running") this.runQueue.cancel(run.id);
+		}
+		this.runQueue = null;
 		this.systemBackup = null;
 		this.policies = null;
 		this.schedules = null;
@@ -5072,64 +5546,180 @@ var BackupOrchestratorAddon = class extends BaseAddon {
 		return path$1.join(this.stagingDir, filename);
 	}
 	/**
-	* Build a single archive in the private staging dir, then push
-	* it to every selected destination via the storage cap's chunked
-	* upload protocol. Per-destination errors are logged and counted
-	* via allSettled semantics — one bad sink doesn't kill the run. The
-	* staging file is deleted in `finally` so a crash mid-fanout doesn't
-	* leak.
+	* Boot-time staging hygiene. Sweeps the staging dir (sparing an
+	* archive a pending-restore marker references — the boot hook has
+	* not consumed it yet), then reports — without touching — the LEGACY
+	* staging dir inside `addons-data`, where pre-move leaks live. The
+	* legacy dir held 5.1 GB on the hub; deleting operator-visible
+	* gigabytes silently is not this addon's call, so it warns with the
+	* footprint instead.
+	*/
+	async cleanStagingArea() {
+		const marker = this.systemBackup?.readPendingMarker() ?? null;
+		const keepPaths = marker ? [marker.archivePath] : [];
+		try {
+			const swept = await sweepStagingDir({
+				stagingDir: this.stagingDir,
+				keepPaths,
+				logger: this.ctx.logger
+			});
+			if (swept.removedCount > 0) this.ctx.logger.info("backup staging swept — leaked transient files removed", { meta: {
+				stagingDir: this.stagingDir,
+				removedCount: swept.removedCount,
+				freedBytes: swept.freedBytes,
+				keptForPendingRestore: swept.keptCount
+			} });
+		} catch (err) {
+			this.ctx.logger.warn("backup staging sweep failed — continuing", { meta: {
+				stagingDir: this.stagingDir,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+		const legacyDir = path$1.join(this.ctx.dataDir, "staging");
+		try {
+			const legacy = await measureDirectoryFootprint(legacyDir);
+			if (legacy.present && legacy.fileCount > 0) this.ctx.logger.warn("legacy backup staging dir still holds files inside addons-data — excluded from archives, but the disk space is only reclaimed by deleting it", { meta: {
+				legacyDir,
+				fileCount: legacy.fileCount,
+				totalBytes: legacy.totalBytes
+			} });
+		} catch {}
+	}
+	/**
+	* Trigger a backup run through the global execution queue (D342):
+	* at most one archive build at a time, a trigger that arrives while
+	* one is in flight WAITS (or joins an identical queued run), and the
+	* result says which happened. The call still resolves when the run
+	* terminates; a cancelled run resolves with `cancelled: true` and
+	* whatever entries landed before the stop — a deliberate operator
+	* cancel is an outcome, not an error.
 	*/
 	async triggerBackup(input) {
+		if (!this.runQueue) throw new Error("orchestrator not initialized");
+		const request = {
+			...input?.destinations ? { destinations: input.destinations } : {},
+			...input?.locations ? { locations: input.locations } : {},
+			...input?.label !== void 0 ? { label: input.label } : {},
+			...input?.retentionCount !== void 0 ? { retentionCount: input.retentionCount } : {}
+		};
+		const submitted = this.runQueue.submit(request);
+		if (submitted.queued) this.ctx.logger.info(submitted.joined ? "backup trigger: identical run already queued — joined it" : "backup trigger: a run is in flight — enqueued behind it", { meta: { runId: submitted.runId } });
+		let entries;
+		try {
+			entries = await submitted.result;
+		} catch (err) {
+			if (!(err instanceof BackupCancelledError)) throw err;
+			entries = [];
+		}
+		const finalState = this.runQueue?.getRun(submitted.runId)?.state;
+		return {
+			runId: submitted.runId,
+			queued: submitted.queued,
+			joined: submitted.joined,
+			cancelled: finalState === "cancelled",
+			entries
+		};
+	}
+	/** Wire `backup.listRuns` — queued + active + bounded history. */
+	async listRuns() {
+		return this.runQueue?.listRuns() ?? [];
+	}
+	/**
+	* Wire `backup.cancel`. Delegates to the queue: a queued run is
+	* removed before it starts; the running run's abort signal fires and
+	* `runBackupBuild` stops the tar/upload streams and deletes its
+	* staging archive on the way out.
+	*/
+	async cancelRun(input) {
+		const cancelled = this.runQueue?.cancel(input.runId) ?? false;
+		if (cancelled) this.ctx.logger.info("backup run cancel requested", { meta: { runId: input.runId } });
+		else this.ctx.logger.warn("backup cancel: run unknown or already terminal", { meta: { runId: input.runId } });
+		return { cancelled };
+	}
+	/**
+	* Execute ONE backup run — only ever called by the queue, never
+	* directly (the queue is the single serialisation authority).
+	* Builds the archive in the private staging dir, then pushes it to
+	* every selected destination via the storage cap's chunked upload
+	* protocol. Per-destination errors are logged and recorded on the
+	* run — one bad sink doesn't kill the run.
+	*
+	* Cleanup contract (D342): the staging file is deleted in `finally`,
+	* which covers success, per-destination failure, build failure AND
+	* cancellation alike. The only leak this cannot cover — the process
+	* dying inside the run — is reclaimed by the boot sweep in
+	* `cleanStagingArea`.
+	*/
+	async runBackupBuild(input, signal, progress) {
 		if (!this.systemBackup) throw new Error("orchestrator not initialized");
-		const targets = await this.resolveTargets(input?.destinations);
+		const targets = await this.resolveTargets(input.destinations !== void 0 ? [...input.destinations] : void 0);
 		if (targets.length === 0) {
 			this.ctx.logger.warn("backup trigger: no destinations selected");
 			return [];
 		}
+		progress.setDestinations(targets.map((t) => t.id));
 		const policies = await this.loadPoliciesIndexed(targets.map((t) => t.id));
 		const archiveId = randomUUID();
 		const archiveFilename = `${archiveId}.tar.gz`;
 		const cachePath = await this.stagingPath(archiveFilename);
 		const result = await this.systemBackup.createArchive({
 			archivePath: cachePath,
-			...input?.locations ? { locations: input.locations } : {}
+			...input.locations ? { locations: [...input.locations] } : {},
+			signal,
+			onArchiveBytes: (bytes) => progress.setStagedBytes(bytes)
 		});
+		progress.setArchiveSize(result.sizeBytes);
+		progress.setPhase("uploading");
 		try {
 			const entries = [];
 			const createdAt = Date.now();
-			for (const dest of targets) try {
-				const policy = policies.get(dest.id) ?? this.fallbackPolicy(dest.id);
-				const stored = await this.uploadAndIndex({
-					locationId: dest.id,
-					archiveId,
-					archiveFilename,
-					cachePath,
-					sizeBytes: result.sizeBytes,
-					archiveManifest: result.manifest,
-					retentionCount: input?.retentionCount ?? policy.retentionCount,
-					createdAt,
-					label: formatArchiveLabel(dest.id, createdAt, input?.label)
-				});
-				entries.push(stored);
-				this.ctx.eventBus.emit({
-					id: randomUUID(),
-					timestamp: /* @__PURE__ */ new Date(),
-					source: {
-						type: "addon",
-						id: "backup-orchestrator"
-					},
-					category: EventCategory.BackupCompleted,
-					data: {
+			for (const dest of targets) {
+				if (signal.aborted) {
+					this.ctx.logger.info("backup run cancelled — skipping remaining destinations", { meta: {
+						runCancelledAfter: entries.length,
+						skippedDestinationIds: targets.slice(targets.indexOf(dest)).map((t) => t.id)
+					} });
+					break;
+				}
+				try {
+					const policy = policies.get(dest.id) ?? this.fallbackPolicy(dest.id);
+					const stored = await this.uploadAndIndex({
+						locationId: dest.id,
+						archiveId,
+						archiveFilename,
+						cachePath,
+						sizeBytes: result.sizeBytes,
+						archiveManifest: result.manifest,
+						retentionCount: input.retentionCount ?? policy.retentionCount,
+						createdAt,
+						label: formatArchiveLabel(dest.id, createdAt, input.label),
+						signal,
+						onUploadedBytes: (bytes) => progress.setUploadedBytes(bytes)
+					});
+					entries.push(stored);
+					progress.destinationCompleted(dest.id);
+					this.ctx.eventBus.emit({
+						id: randomUUID(),
+						timestamp: /* @__PURE__ */ new Date(),
+						source: {
+							type: "addon",
+							id: "backup-orchestrator"
+						},
+						category: EventCategory.BackupCompleted,
+						data: {
+							destinationId: dest.id,
+							backupId: stored.id,
+							sizeMB: Math.round((stored.sizeBytes ?? 0) / (1024 * 1024))
+						}
+					});
+				} catch (err) {
+					if (err instanceof BackupCancelledError) continue;
+					progress.destinationFailed(dest.id);
+					this.ctx.logger.error("backup trigger: destination failed", { meta: {
 						destinationId: dest.id,
-						backupId: stored.id,
-						sizeMB: Math.round((stored.sizeBytes ?? 0) / (1024 * 1024))
-					}
-				});
-			} catch (err) {
-				this.ctx.logger.error("backup trigger: destination failed", { meta: {
-					destinationId: dest.id,
-					error: err instanceof Error ? err.message : String(err)
-				} });
+						error: err instanceof Error ? err.message : String(err)
+					} });
+				}
 			}
 			return entries;
 		} finally {
@@ -5158,6 +5748,10 @@ var BackupOrchestratorAddon = class extends BaseAddon {
 			let offset = 0;
 			const stream = fs.createReadStream(input.cachePath, { highWaterMark: UPLOAD_CHUNK_BYTES });
 			for await (const rawChunk of stream) {
+				if (input.signal?.aborted) {
+					stream.destroy();
+					throw new BackupCancelledError(`backup upload to ${input.locationId} cancelled mid-stream`);
+				}
 				const chunk = toBufferChunk(rawChunk);
 				const data = new Uint8Array(chunk.byteLength);
 				data.set(chunk);
@@ -5167,6 +5761,7 @@ var BackupOrchestratorAddon = class extends BaseAddon {
 					data
 				});
 				offset += data.byteLength;
+				input.onUploadedBytes?.(offset);
 			}
 			await this.ctx.api.storage.finalizeUpload.mutate({ uploadId });
 		} catch (err) {