@camstack/system 1.2.60 → 1.2.62

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { a as __toCommonJS, i as __require, n as __esmMin, o as __toESM$1, r as __exportAll, t as __commonJSMin$1 } from "./chunk-CNf5ZN-e.mjs";
-import { $ as procedureAuthKey, Ct as asJsonObject$1, Dt as emitDownForOwnedCaps, Et as createEvent, Ft as readinessKey, H as kebabToCamel, It as resolveCapMount, K as logLevelAtMost, L as isArrayOutputSchema, Lt as scopeKey, Nt as parseJsonObject, P as extractNestedAddonId, Pt as parseJsonUnknown$1, R as isCollectionArrayMethod, Tt as asString$1, U as lifecycleJobSchema, V as isVoidInput, X as objectInputDeclaresAddonId, bt as ReadinessRegistry, c as METHOD_ACCESS_MAP, ft as errMsg$1, gt as DEVICE_STATUS_METHOD, h as addonSettingsCapability, ht as DEVICE_SETTINGS_CONTRIBUTION_METHODS, kt as expandCapMethods, l as RUNTIME_DEFAULTS, mt as DATAPLANE_SECRET_HEADER$1, q as looseSchema, t as ALL_CAPABILITY_DEFINITIONS, wt as asNumber, xt as ReadinessTimeoutError, z as isObjectInput, zt as EventCategory$1 } from "./dist-C5XpOjbI.mjs";
+import { $ as procedureAuthKey, Ct as asJsonObject$1, Dt as emitDownForOwnedCaps, Et as createEvent, Ft as readinessKey, H as kebabToCamel, It as resolveCapMount, K as logLevelAtMost, L as isArrayOutputSchema, Lt as scopeKey, Nt as parseJsonObject, P as extractNestedAddonId, Pt as parseJsonUnknown$1, R as isCollectionArrayMethod, Tt as asString$1, U as lifecycleJobSchema, V as isVoidInput, X as objectInputDeclaresAddonId, bt as ReadinessRegistry, c as METHOD_ACCESS_MAP, ft as errMsg$1, gt as DEVICE_STATUS_METHOD, h as addonSettingsCapability, ht as DEVICE_SETTINGS_CONTRIBUTION_METHODS, kt as expandCapMethods, l as RUNTIME_DEFAULTS, mt as DATAPLANE_SECRET_HEADER$1, q as looseSchema, t as ALL_CAPABILITY_DEFINITIONS, wt as asNumber, xt as ReadinessTimeoutError, z as isObjectInput, zt as EventCategory$1 } from "./dist-DnKpFaP1.mjs";
 import { a as downloadModel, c as getModelFilePath, d as contentTypeFor, f as createAuthenticatedFileServer, h as resolveFilePath, i as downloadFile, l as isModelDownloaded, m as parseTokenizedUrl, n as collectModelFiles, o as ensureModel, p as parseRangeHeader, r as deleteModelFromDisk, s as fetchJson, t as ModelDownloadService, u as createFileDataPlaneHandler } from "./model-download-service-D8B-4ktF.mjs";
 import { $ as buildNativeCapProxy, A as createHubCapForwardService, B as AGENT_CAP_FWD_ACTION, C as brokerTransportLink, Ct as resolveAddonClass, D as localProviderLink, E as ipcParentLink, F as createUdsLogger, G as callWithServiceDiscovery, H as CapRouteResolver, I as createUdsLoggerWithControl, J as UdsLocalTransportServer, K as createLocalTransport, L as LocalChildClient, M as createUdsEventBridge, N as createUdsEventBus, O as HUB_CAP_FWD_ACTION, P as udsChildLogToWorkerEntry, Q as encodeFrame, R as LocalChildRegistry, S as brokerCallForCap, St as runNpm, T as ipcChildLink, U as CapRouteError, V as AGENT_CAP_FWD_SERVICE, W as classifyCapRoute, X as localEndpointPath, Y as SocketChannel, Z as FrameDecoder, _ as createKernelHwAccel, _t as CapabilityHandle, a as getWorkerDeviceRegistry, b as __resetCapUsageRegistryForTests, bt as installManifestNativeDeps, c as setHubConnected, ct as NATIVE_PROVIDER_SERVICE_INFIX, d as getBrokerEventBus, dt as capBareAction, et as buildUdsNativeCapProxy, f as getMoleculerEventStats, ft as capServiceName, g as AddonDepsManager, gt as DeviceRegistry, h as subscribePassthrough, ht as serializeTypedArrays, i as createUdsAddonContext, it as mountNativeCapService, j as createParentUnownedCallHandler, k as HUB_CAP_FWD_SERVICE, l as EVENT_TOPIC_PREFIX, lt as capActionName, m as setNodeEventInterest, mt as deserializeTypedArrays, n as adaptBrokerToCluster, o as getOrInitReadinessRegistry, ot as createAddonService, p as registerEventBusService, pt as parseCapAction, q as UdsLocalTransportClient, r as createAddonContext, s as getOrInitReadinessRegistryForClient, st as validateProviderRegistrations, t as installManifestPythonDeps, tt as createBrokerDeviceManagerApi, u as clusterEventTopic, ut as capActionSuffix, v as resolveHwAccel, vt as CapabilityUnavailableError, w as buildLinkChain, wt as createAddonDataPlaneFacility, x as getCapUsageRegistry, xt as resolveNpmInvocation, y as CapUsageRegistry, yt as copyBundledNativeModules, z as UDS_NO_ROUTE_PREFIX } from "./manifest-python-deps-CX5tGRqf.mjs";
 import { n as getSinglePidStats, t as getPidStats } from "./resource-monitor-BkP504Vq.mjs";
@@ -28,6 +28,7 @@ import { DeviceManagerAddon } from "./builtins/device-manager/device-manager.add
 import "./builtins/device-manager/index.mjs";
 import { t as CustomActionRegistry } from "./custom-action-registry-F__gp_VX.mjs";
 import * as v8 from "node:v8";
+import * as vm from "node:vm";
 import { PYTHON_VERSION, buildBinaryPath, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements } from "@camstack/types/node";
 import { z } from "zod";
 import { X509Certificate, createHash, randomUUID, timingSafeEqual } from "node:crypto";
@@ -40,7 +41,6 @@ import { asJsonObject, errMsg, parseJsonUnknown } from "@camstack/types/addon";
 import { execFile, spawn } from "node:child_process";
 import * as util$10 from "node:util";
 import { promisify } from "node:util";
-import * as vm from "node:vm";
 import * as os$18 from "node:os";
 import { lstat, readdir, readlink, realpath } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -52,13 +52,15 @@ import "path";
 import { createRequire } from "module";
 //#region src/kernel/heap-watch.ts
 /**
-* heap-watch — hub-main's own memory, on the record.
+* heap-watch — hub-main's own memory, on the record, and returned to the OS.
 *
 * ## Why this exists
 *
-* hub-main is launched with `--max-old-space-size=1536` (docker-entrypoint) and
-* has logged NOTHING about its own heap. When it died on 2026-08-01/02 the only
-* trace was V8's own stderr line:
+* hub-main used to be launched with `--max-old-space-size=1536` (docker-entrypoint;
+* the cap was removed on 2026-08-02, so the live ceiling is now V8's own default —
+* 4288MB in this container — and this module reads it at runtime rather than
+* assuming a number). It logged NOTHING about its own heap. When it died on
+* 2026-08-01/02 the only trace was V8's own stderr line:
 *
 *     FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
 *
@@ -86,6 +88,41 @@ import { createRequire } from "module";
 * `--max-old-space-size` and are most of the gap between a 1.5GB cap and the
 * ~2.05GB RSS observed live: a diagnosis that only looks at the JS heap
 * misreads that process by 500MB.
+*
+* ## And then the heartbeat explained the "off-heap leak", which was not one
+*
+* 2026-08-08, measured on the live hub over 1019 consecutive samples and seven
+* separate boots: **hub-main's RSS is a HIGH-WATER MARK, not a leak.** In every
+* one of those 1019 samples RSS was >= the running maximum of
+* `heapTotal + external`, never once below it, and
+* `RSS_peak - peak(heapTotal + external)` landed between 874MB and 1639MB on
+* every boot — a roughly constant native floor on top of a number that only
+* ever goes up. RSS tracked the highest point the process ever reached and
+* stayed there: 3.3GB -> 4.5GB -> 5.2GB, and 7.8GB on the worst boot.
+*
+* Two things push that peak, and neither is a retained object:
+*
+*  - the JS heap sawtooths to 2.0-2.8GB because the ceiling is 4288MB and
+*    nothing creates pressure before then;
+*  - `arrayBuffers` accumulates DEAD Buffers — up to 3.65GB — because V8 only
+*    sweeps them on a major GC. Eleven collapses were captured, and every
+*    single one coincides with `heapUsed` dropping to its ~650MB floor. No code
+*    released a reference at 13:23:03; a mark-compact ran.
+*
+* At the peak V8 has committed the pages, and **an ordinary major GC does not
+* give them back.** Proven on the production hub: `smaps` showed 10,819 mapped
+* 256KB pages (V8's `kRegularPageSize`) holding 2704MB while V8 itself reported
+* `total_physical_size` of only 846MB — ~7,800 pages committed, resident, and
+* outside V8's own accounting. One `gc({ flavor: 'last-resort' })` took 417ms
+* and returned RSS 3355MB -> 1237MB, pages 10,819 -> 2,963.
+*
+* So the fix for the "~3GB/2h off-heap growth" is not a retainer hunt. It is to
+* ask V8 for the pages back when the process is visibly holding more than it is
+* using — which is what `shouldReclaim` decides and what the heartbeat now does.
+*
+* The cost is a 250-450ms stop-the-world on the hub's router process, bounded to
+* once per `HEAP_RECLAIM_MIN_INTERVAL_MS`. The alternative, measured, is a
+* ratchet to 7.8GB and the OOM that ends it.
 */
 /** Heartbeat period. Slow enough to be free, fast enough that the sample before
 *  a fatal is recent. */
@@ -93,6 +130,20 @@ var HEAP_WATCH_INTERVAL_MS = 6e4;
 /** Warn above this share of the heap ceiling. Chosen so the warning precedes
 *  the fatal by more than one interval under realistic growth. */
 var HEAP_WATCH_WARN_RATIO = .8;
+/**
+* Reclaim once the process holds this many MB beyond what it is USING.
+*
+* Live calibration, both readings from the same hub minutes apart: 2491MB
+* stranded before the reclaim, 438MB after. 438MB is this process's irreducible
+* native floor (sqlite pages, libvips, sharp, thread stacks, node's own text) —
+* collecting against it would buy nothing and cost a stall every minute. 1536
+* sits clear of that floor and still fires ~1.1GB before the ratchet is worth
+* anything, so it triggers on the real condition and stops as soon as it is fixed.
+*/
+var HEAP_RECLAIM_TRIGGER_MB = 1536;
+/** Floor on how often the stop-the-world may run. 250-450ms measured, so ten
+*  minutes keeps the worst case under 0.1% of the router's time. */
+var HEAP_RECLAIM_MIN_INTERVAL_MS = 6e5;
 var MB = (bytes) => Math.round(bytes / 1048576);
 /**
 * Build a sample from raw readings. Pure so the thresholds are testable without
@@ -115,6 +166,47 @@ var consoleSink = {
 	info: (line) => console.log(line),
 	warn: (line) => console.warn(line)
 };
+/**
+* RSS the process is holding but not using.
+*
+* The subtrahend is heapUSED, not heapTotal, deliberately: the pages V8
+* committed at a sawtooth peak and no longer needs are counted inside heapTotal,
+* and they are precisely what this number exists to see.
+*/
+function strandedMb(s) {
+	return s.rssMb - s.heapUsedMb - s.externalMb;
+}
+/** Whether it is worth paying a stop-the-world to get those pages back. */
+function shouldReclaim(s, triggerMb = HEAP_RECLAIM_TRIGGER_MB) {
+	return strandedMb(s) > triggerMb;
+}
+function isGcFunction(value) {
+	return typeof value === "function";
+}
+/**
+* Build the reclaimer without requiring `--expose-gc` on argv.
+*
+* The flag is turned on, the function captured, and the flag turned straight
+* back off — a global `gc` left reachable by application code is a footgun, and
+* requiring an argv change would mean this cannot ship without a new image.
+* Verified against the live hub before being written: 266ms, RSS 1453 -> 1237.
+*
+* Returns undefined if V8 declines, so the caller keeps a heartbeat either way.
+*/
+function createV8Reclaimer() {
+	try {
+		v8.setFlagsFromString("--expose-gc");
+		const gc = vm.runInNewContext("gc");
+		v8.setFlagsFromString("--no-expose-gc");
+		if (!isGcFunction(gc)) return void 0;
+		return () => gc({
+			execution: "sync",
+			flavor: "last-resort"
+		});
+	} catch {
+		return;
+	}
+}
 function format$1(label, s) {
 	return `[mem] ${label} rss=${s.rssMb}MB heapUsed=${s.heapUsedMb}MB heapTotal=${s.heapTotalMb}MB heapLimit=${s.heapLimitMb}MB used=${Math.round(s.usedRatio * 100)}% external=${s.externalMb}MB arrayBuffers=${s.arrayBuffersMb}MB`;
 }
@@ -124,13 +216,38 @@ function format$1(label, s) {
 * `unref`ed so it can never hold the process open, and every read is wrapped:
 * a diagnostic that can crash the process it watches is worse than none.
 */
-function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEAP_WATCH_INTERVAL_MS) {
+function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEAP_WATCH_INTERVAL_MS, reclaimOptions) {
+	const readMemory = reclaimOptions?.readMemory ?? (() => process.memoryUsage());
+	const now = reclaimOptions?.now ?? (() => Date.now());
+	const triggerMb = reclaimOptions?.triggerMb ?? 1536;
+	const minIntervalMs = reclaimOptions?.minIntervalMs ?? 6e5;
+	let lastReclaimAt = Number.NEGATIVE_INFINITY;
+	const read = () => {
+		const limit = reclaimOptions?.heapLimitBytes ?? v8.getHeapStatistics().heap_size_limit;
+		return buildHeapSample(readMemory(), limit);
+	};
+	const maybeReclaim = (sample) => {
+		if (reclaimOptions === void 0) return;
+		if (!shouldReclaim(sample, triggerMb)) return;
+		if (now() - lastReclaimAt < minIntervalMs) return;
+		lastReclaimAt = now();
+		const startedAt = now();
+		try {
+			reclaimOptions.reclaim();
+		} catch (error) {
+			sink.warn(`[mem] reclaim failed — ${error instanceof Error ? error.message : String(error)}`);
+			return;
+		}
+		const after = read();
+		sink.info(`[mem] reclaim ${label} stranded=${strandedMb(sample)}MB rss=${sample.rssMb}MB→${after.rssMb}MB freed=${sample.rssMb - after.rssMb}MB arrayBuffers=${sample.arrayBuffersMb}MB→${after.arrayBuffersMb}MB took=${now() - startedAt}ms`);
+	};
 	const tick = () => {
 		try {
-			const sample = buildHeapSample(process.memoryUsage(), v8.getHeapStatistics().heap_size_limit);
+			const sample = read();
 			const line = format$1(label, sample);
 			if (sample.nearLimit) sink.warn(`${line} — APPROACHING HEAP LIMIT`);
 			else sink.info(line);
+			maybeReclaim(sample);
 		} catch {}
 	};
 	const timer = setInterval(tick, intervalMs);
@@ -3231,7 +3348,12 @@ var MANIFEST_VERSION = 1;
 * workspace source. Trusting the dirent there finds zero addons on disk, which
 * with pruning would empty a developer's manifest on the next boot.
 */
-function isDirLike(p) {
+/** `@camstack/system` → `system`: the directory a package must live in. */
+function packageDirName$1(declaredName) {
+	const slash = declaredName.lastIndexOf("/");
+	return slash === -1 ? declaredName : declaredName.slice(slash + 1);
+}
+function isDirLike$1(p) {
 	try {
 		return fs$17.statSync(p).isDirectory();
 	} catch {
@@ -3365,10 +3487,10 @@ var AddonManifest = class {
 		/** Package name → version, for every ADDON package actually installed. */
 		const onDisk = /* @__PURE__ */ new Map();
 		for (const scope of fs$17.readdirSync(addonsDir, { withFileTypes: true })) {
-			if (!scope.name.startsWith("@") || !isDirLike(path$39.join(addonsDir, scope.name))) continue;
+			if (!scope.name.startsWith("@") || !isDirLike$1(path$39.join(addonsDir, scope.name))) continue;
 			const scopeDir = path$39.join(addonsDir, scope.name);
 			for (const pkg of fs$17.readdirSync(scopeDir, { withFileTypes: true })) {
-				if (!isDirLike(path$39.join(scopeDir, pkg.name))) continue;
+				if (!isDirLike$1(path$39.join(scopeDir, pkg.name))) continue;
 				const pkgJsonPath = path$39.join(scopeDir, pkg.name, "package.json");
 				if (!fs$17.existsSync(pkgJsonPath)) continue;
 				let pkgJson;
@@ -3382,6 +3504,7 @@ var AddonManifest = class {
 				if (!pkgJson.name || !pkgJson.version) continue;
 				const addons = pkgJson.camstack?.addons;
 				if (!Array.isArray(addons) || addons.length === 0) continue;
+				if (packageDirName$1(pkgJson.name) !== pkg.name) continue;
 				onDisk.set(pkgJson.name, pkgJson.version);
 			}
 		}
@@ -4899,6 +5022,199 @@ function isDirEntry(entry, parentDir) {
 	return false;
 }
 //#endregion
+//#region src/kernel/addon-residue.ts
+/**
+* Residue quarantine for the ONE addon root.
+*
+* ── The bug class this closes ──────────────────────────────────────────────
+* `<dataDir>/addons/@camstack/<pkg>` is the only directory a node loads addons
+* from. Renaming a package inside it does NOT archive it — the directory name
+* is decoration, and three independent consumers key on the `package.json`
+* they find inside:
+*
+*   - `AddonLoader.loadFromDirectory` walks `@scope/*` and loads anything with
+*     a `package.json`; its skip list is keyed on the PACKAGE name, so
+*     `@camstack/system.bak-pre-unshadow` was never skipped;
+*   - the agent's `resolveAddonPackageDirs` scans on the same rule;
+*   - `AddonManifest.reconcileFromDisk` does `onDisk.set(pkgJson.name, …)`,
+*     so the backup's version becomes the version the manifest — and every
+*     surface reading it — REPORTS.
+*
+* Measured 2026-08-07/08 on the live cluster:
+*
+*   little-unraid  `@camstack/system.bak-pre-unshadow` — no package.json left,
+*                  so not loadable, but the agent main process held five live
+*                  mappings of `better_sqlite3.node` out of it (D87).
+*   macmini        `@camstack/system.bak-pre-1272-1786129145` — still declares
+*                  `@camstack/system@1.2.3` (17 days old, 97 MB). The data root
+*                  has NO `addons/@camstack/system` directory at all, yet the
+*                  manifest reports `@camstack/system 1.2.3` — read straight
+*                  out of the backup. The live process still had the backup's
+*                  `better_sqlite3.node` mapped `txt` against a 1.2.61 closure.
+*
+* ── Why quarantine and not delete ─────────────────────────────────────────
+* The same evening, a cleanup that DELETED what it judged to be a shadow copy
+* removed the only builtins an agent had and gutted the node. So this never
+* deletes: it renames out of the scanned root into `.quarantine/`, logs every
+* move by name, reason and both paths, and leaves the bytes recoverable. A
+* silent sweep reads as "nothing was here", which is the failure mode that
+* made the original one unobservable.
+*
+* `.quarantine` sits beside `.staging` / `.backups` / `.evicting` under the
+* addon root: dot-prefixed, carrying no `package.json` at its top level, so no
+* scanner descends into it.
+*/
+/** Where residue is moved to, relative to the addon root. */
+var QUARANTINE_DIRNAME = ".quarantine";
+/**
+* A backup marker: a `.bak` / `.old` / `.orig` segment, not merely those
+* letters. `.backups` — the installer's own rollback store — must NOT match,
+* and it is also excluded by the dot rule below; the pattern stays tight
+* anyway so the two guards are independent.
+*/
+var BACKUP_MARKER = /\.(bak|old|orig)(?![a-z])/i;
+/** Installer-owned stores and node's own tree. Never candidates. */
+function isReservedDir(dirName) {
+	return dirName.startsWith(".") || dirName === "node_modules";
+}
+/** `@camstack/system` → `system`; `foo` → `foo`. */
+function packageDirName(declaredName) {
+	const slash = declaredName.lastIndexOf("/");
+	return slash === -1 ? declaredName : declaredName.slice(slash + 1);
+}
+/**
+* Is this directory residue? Returns the verdict, or null to keep it.
+*
+* A directory with no `package.json` is NOT residue on that ground alone —
+* `models/`, a half-finished copy, a scratch dir are all absence, not a
+* rename. Only a backup marker condemns one.
+*/
+function classifyAddonDir(candidate) {
+	const { dirName, declaredName } = candidate;
+	if (isReservedDir(dirName)) return null;
+	if (BACKUP_MARKER.test(dirName)) return {
+		dirName,
+		declaredName,
+		reason: "backup-residue"
+	};
+	if (declaredName !== null && packageDirName(declaredName) !== dirName) return {
+		dirName,
+		declaredName,
+		reason: "name-mismatch"
+	};
+	return null;
+}
+function selectAddonResidue(candidates) {
+	const out = [];
+	for (const candidate of candidates) {
+		const verdict = classifyAddonDir(candidate);
+		if (verdict !== null) out.push(verdict);
+	}
+	return out;
+}
+function readDeclaredName(dir) {
+	try {
+		const parsed = JSON.parse(fs$17.readFileSync(path$39.join(dir, "package.json"), "utf-8"));
+		if (typeof parsed !== "object" || parsed === null) return null;
+		const name = parsed.name;
+		return typeof name === "string" ? name : null;
+	} catch {
+		return null;
+	}
+}
+function readDeclaredVersion(dir) {
+	try {
+		const parsed = JSON.parse(fs$17.readFileSync(path$39.join(dir, "package.json"), "utf-8"));
+		if (typeof parsed !== "object" || parsed === null) return null;
+		const version = parsed.version;
+		return typeof version === "string" ? version : null;
+	} catch {
+		return null;
+	}
+}
+function isDirLike(p) {
+	try {
+		return fs$17.statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+/** `<scope>__<dir>`, suffixed until free — two sweeps must not overwrite. */
+function freeQuarantineTarget(store, scope, dirName) {
+	const base = scope === null ? dirName : `${scope.replace("@", "")}__${dirName}`;
+	let candidate = path$39.join(store, base);
+	let n = 1;
+	while (fs$17.existsSync(candidate)) {
+		candidate = path$39.join(store, `${base}-${n}`);
+		n += 1;
+	}
+	return candidate;
+}
+/**
+* Move every residue directory under `addonsDir` into `addonsDir/.quarantine`.
+*
+* Runs at boot, BEFORE anything scans the root or seeds into it — a residue
+* that is still present when the loader walks has already been installed.
+* Never throws, never deletes; a move that fails is reported and left in
+* place, which is strictly better than a half-moved package.
+*/
+function quarantineAddonResidue(addonsDir, log) {
+	const quarantined = [];
+	const failed = [];
+	if (!fs$17.existsSync(addonsDir)) return {
+		quarantined,
+		failed
+	};
+	const store = path$39.join(addonsDir, QUARANTINE_DIRNAME);
+	const scan = (parent, scope) => {
+		let names;
+		try {
+			names = fs$17.readdirSync(parent);
+		} catch {
+			return;
+		}
+		for (const dirName of names) {
+			const full = path$39.join(parent, dirName);
+			if (!isDirLike(full)) continue;
+			if (scope === null && dirName.startsWith("@")) {
+				scan(full, dirName);
+				continue;
+			}
+			const verdict = classifyAddonDir({
+				dirName,
+				declaredName: readDeclaredName(full)
+			});
+			if (verdict === null) continue;
+			const version = readDeclaredVersion(full);
+			const to = freeQuarantineTarget(store, scope, dirName);
+			try {
+				fs$17.mkdirSync(store, { recursive: true });
+				fs$17.renameSync(full, to);
+			} catch (err) {
+				const error = err instanceof Error ? err.message : String(err);
+				failed.push({
+					...verdict,
+					from: full,
+					error
+				});
+				log(`[addons] residue quarantine FAILED for ${full} (${verdict.reason}) — ${error}. It stays on the addon root and will be loaded, scanned and reported as an install.`);
+				continue;
+			}
+			quarantined.push({
+				...verdict,
+				from: full,
+				to
+			});
+			log(`[addons] quarantined ${verdict.reason} ${full} → ${to} (declares ${verdict.declaredName ?? "no package name"}${version === null ? "" : `@${version}`}). A renamed package dir is INSTALLED, not archived — nothing was deleted.`);
+		}
+	};
+	scan(addonsDir, null);
+	return {
+		quarantined,
+		failed
+	};
+}
+//#endregion
 //#region src/kernel/workspace-detect.ts
 /**
 * Detect whether we're running inside the monorepo workspace.
@@ -94510,4 +94826,4 @@ var LifecycleJobEngine = class {
 	}
 };
 //#endregion
-export { AGENT_CAP_FWD_ACTION, AGENT_CAP_FWD_SERVICE, AGENT_READINESS_SERVICE_NAME, ALL_CAPABILITY_DEFINITIONS, AddonApiFactory, AddonDepsManager, AddonEngineManager, AddonHealthMonitor, AddonInstaller, AddonLoader, AddonManifest, AddonRouteRegistry, AlertCenterAddon, ApiKeyManager, AuthManager, CLUSTER_SECRET_MISMATCH_TYPE, CLUSTER_SECRET_REJECTED_EXIT_CODE, CORE_CAP_SERVICE_NAME, CapRouteError, CapRouteResolver, CapUsageRegistry, CapabilityHandle, CapabilityRegistry, CapabilityUnavailableError, ConfigManager, ConfigStore, ConsoleDestination, ConsoleLoggingAddon, CoreBlocksAddon, CustomActionRegistry, DEFAULT_DATA_PATH, DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, DataPlaneRegistry, DeviceManagerAddon, DeviceRegistry, DeviceStore, EVENT_TOPIC_PREFIX, EngineManagerResolver, EventBus, FeatureManager, FilesystemStorageAddon, FilesystemStorageProvider, FrameDecoder, FsStorageBackend, HEALTH_MONITOR_GRACE_PERIOD_MS, HEALTH_MONITOR_RETRY_INTERVALS_MS, HEALTH_MONITOR_TICK_MS, HEAP_WATCH_INTERVAL_MS, HEAP_WATCH_WARN_RATIO, HUB_CAP_FWD_ACTION, HUB_CAP_FWD_SERVICE, HubForwarderAddon, HubForwarderDestination, HubLogForwarder, HubNodeRegistry, INFRA_CAPABILITIES, IntegrationRegistry, JobJournal, LifecycleJobEngine, LifecycleStateMachine, LivenessMonitorAddon, LocalAuthAddon, LocalChildClient, LocalChildRegistry, LogManager, LogRingBuffer, LokiDestination, LokiLoggingAddon, METHOD_ACCESS_MAP, ModelDownloadService, NATIVE_PROVIDER_SERVICE_INFIX, NATIVE_SCAN_DEPTH, NativeMetricsAddon, NativeMetricsProvider, NetworkQualityTracker, NotificationService, PYTHON_VERSION, PipelineRunner, PipelineValidator, PythonEnvManager, RESTART_MARKER_FILE, RUNTIME_DEFAULTS, ReadinessRegistry, ReadinessTimeoutError, ReplEngine, RingBuffer, ScopedLogger, ScopedTokenManager, SocketChannel, SqliteSettingsAddon, SqliteSettingsBackend, StagingArea, StorageLocationManager, StorageManager, StorageOrchestratorAddon, StorageOrchestratorService, SystemConfigAddon, SystemEventBus, TRADITIONAL_NATIVE_PACKAGES, ToastService, UDS_NO_ROUTE_PREFIX, UdsLocalTransportClient, UdsLocalTransportServer, UserManager, WinstonDestination, WinstonLoggingAddon, __resetCapUsageRegistryForTests, adaptBrokerToCluster, addonSettingsCapability, bootstrapSchema, brokerCallForCap, brokerTransportLink, buildBinaryPath, buildCapRouters, buildHeapSample, buildLinkChain, buildNativeCapProxy, buildNodeManifest, buildStorageLocationRegistry, buildUdsNativeCapProxy, builderMountedCapNames, callRegisterNodeWithRetry, callWithServiceDiscovery, capActionName, capActionSuffix, capBareAction, capServiceName, classifyCapRoute, clearPendingRestart, clusterEventTopic, clusterSecretMatches, collectModelFiles, contentTypeFor, copyDirRecursive, copyExtraFileDirs, createAddonContext, createAddonDataPlaneFacility, createAddonService, createAuthenticatedFileServer, createBroker, createBrokerDeviceManagerApi, createCoreCapService, createFileDataPlaneHandler, createHubCapForwardService, createHubService, createKernelHwAccel, createLocalTransport, createParentUnownedCallHandler, createProcessService, createReadinessService, createReadinessServiceForRegistry, createScopedProcessManager, createStreamProbeBrokerService, createUdsAddonContext, createUdsEventBridge, createUdsEventBus, createUdsLogger, createUdsLoggerWithControl, deleteModelFromDisk, deriveAgentListenPort, describeProviderKindDrift, detectWorkspacePackagesDir, downloadBinary, downloadFile, downloadModel, emitDownForOwnedCaps, encodeFrame, ensureAddonNativePrebuilds, ensureBinary, ensureDir, ensureFfmpeg, ensureLibraryBuilt, ensureModel, ensureNativePrebuilds, ensurePython, ensureTlsCert, expandCapMethods, fetchJson, findInPath, formatLogLine, getBrokerEventBus, getCapUsageRegistry, getFfmpegDownloadUrl, getModelFilePath, getMoleculerEventStats, getOrInitReadinessRegistry, getOrInitReadinessRegistryForClient, getPidStats, getPlatformInfo, getPythonDownloadUrl, getRestartMarkerPath, getSinglePidStats, getWorkerDeviceRegistry, hasDotNode, hashClusterSecret, installManifestNativeDeps, installManifestPythonDeps, installPackageFromNpm, installPythonPackages, installPythonRequirements, ipcChildLink, ipcParentLink, isAddonDeploySource, isArrayOutputSchema, isClusterSecretMismatchError, isCollectionArrayMethod, isInfraCapability, isModelDownloaded, isSourceNewer, loadTlsCert, localEndpointPath, localProviderLink, mountNativeCapService, parseCapAction, parseRangeHeader, parseTokenizedUrl, proxyToUpstream, readPendingRestart, readinessKey, registerEventBusService, resolveFilePath, resolveHwAccel, resolveNpmInvocation, runNpm, scheduleSelfRestart, scopeKey, scopesAllowDeviceCap, serializeTypedArrays, setHubConnected, setNodeEventInterest, startHeapWatch, stripCamstackDeps, subscribePassthrough, udsChildLogToWorkerEntry, validateProviderRegistrations, writePendingRestart };
+export { AGENT_CAP_FWD_ACTION, AGENT_CAP_FWD_SERVICE, AGENT_READINESS_SERVICE_NAME, ALL_CAPABILITY_DEFINITIONS, AddonApiFactory, AddonDepsManager, AddonEngineManager, AddonHealthMonitor, AddonInstaller, AddonLoader, AddonManifest, AddonRouteRegistry, AlertCenterAddon, ApiKeyManager, AuthManager, CLUSTER_SECRET_MISMATCH_TYPE, CLUSTER_SECRET_REJECTED_EXIT_CODE, CORE_CAP_SERVICE_NAME, CapRouteError, CapRouteResolver, CapUsageRegistry, CapabilityHandle, CapabilityRegistry, CapabilityUnavailableError, ConfigManager, ConfigStore, ConsoleDestination, ConsoleLoggingAddon, CoreBlocksAddon, CustomActionRegistry, DEFAULT_DATA_PATH, DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, DataPlaneRegistry, DeviceManagerAddon, DeviceRegistry, DeviceStore, EVENT_TOPIC_PREFIX, EngineManagerResolver, EventBus, FeatureManager, FilesystemStorageAddon, FilesystemStorageProvider, FrameDecoder, FsStorageBackend, HEALTH_MONITOR_GRACE_PERIOD_MS, HEALTH_MONITOR_RETRY_INTERVALS_MS, HEALTH_MONITOR_TICK_MS, HEAP_RECLAIM_MIN_INTERVAL_MS, HEAP_RECLAIM_TRIGGER_MB, HEAP_WATCH_INTERVAL_MS, HEAP_WATCH_WARN_RATIO, HUB_CAP_FWD_ACTION, HUB_CAP_FWD_SERVICE, HubForwarderAddon, HubForwarderDestination, HubLogForwarder, HubNodeRegistry, INFRA_CAPABILITIES, IntegrationRegistry, JobJournal, LifecycleJobEngine, LifecycleStateMachine, LivenessMonitorAddon, LocalAuthAddon, LocalChildClient, LocalChildRegistry, LogManager, LogRingBuffer, LokiDestination, LokiLoggingAddon, METHOD_ACCESS_MAP, ModelDownloadService, NATIVE_PROVIDER_SERVICE_INFIX, NATIVE_SCAN_DEPTH, NativeMetricsAddon, NativeMetricsProvider, NetworkQualityTracker, NotificationService, PYTHON_VERSION, PipelineRunner, PipelineValidator, PythonEnvManager, QUARANTINE_DIRNAME, RESTART_MARKER_FILE, RUNTIME_DEFAULTS, ReadinessRegistry, ReadinessTimeoutError, ReplEngine, RingBuffer, ScopedLogger, ScopedTokenManager, SocketChannel, SqliteSettingsAddon, SqliteSettingsBackend, StagingArea, StorageLocationManager, StorageManager, StorageOrchestratorAddon, StorageOrchestratorService, SystemConfigAddon, SystemEventBus, TRADITIONAL_NATIVE_PACKAGES, ToastService, UDS_NO_ROUTE_PREFIX, UdsLocalTransportClient, UdsLocalTransportServer, UserManager, WinstonDestination, WinstonLoggingAddon, __resetCapUsageRegistryForTests, adaptBrokerToCluster, addonSettingsCapability, bootstrapSchema, brokerCallForCap, brokerTransportLink, buildBinaryPath, buildCapRouters, buildHeapSample, buildLinkChain, buildNativeCapProxy, buildNodeManifest, buildStorageLocationRegistry, buildUdsNativeCapProxy, builderMountedCapNames, callRegisterNodeWithRetry, callWithServiceDiscovery, capActionName, capActionSuffix, capBareAction, capServiceName, classifyAddonDir, classifyCapRoute, clearPendingRestart, clusterEventTopic, clusterSecretMatches, collectModelFiles, contentTypeFor, copyDirRecursive, copyExtraFileDirs, createAddonContext, createAddonDataPlaneFacility, createAddonService, createAuthenticatedFileServer, createBroker, createBrokerDeviceManagerApi, createCoreCapService, createFileDataPlaneHandler, createHubCapForwardService, createHubService, createKernelHwAccel, createLocalTransport, createParentUnownedCallHandler, createProcessService, createReadinessService, createReadinessServiceForRegistry, createScopedProcessManager, createStreamProbeBrokerService, createUdsAddonContext, createUdsEventBridge, createUdsEventBus, createUdsLogger, createUdsLoggerWithControl, createV8Reclaimer, deleteModelFromDisk, deriveAgentListenPort, describeProviderKindDrift, detectWorkspacePackagesDir, downloadBinary, downloadFile, downloadModel, emitDownForOwnedCaps, encodeFrame, ensureAddonNativePrebuilds, ensureBinary, ensureDir, ensureFfmpeg, ensureLibraryBuilt, ensureModel, ensureNativePrebuilds, ensurePython, ensureTlsCert, expandCapMethods, fetchJson, findInPath, formatLogLine, getBrokerEventBus, getCapUsageRegistry, getFfmpegDownloadUrl, getModelFilePath, getMoleculerEventStats, getOrInitReadinessRegistry, getOrInitReadinessRegistryForClient, getPidStats, getPlatformInfo, getPythonDownloadUrl, getRestartMarkerPath, getSinglePidStats, getWorkerDeviceRegistry, hasDotNode, hashClusterSecret, installManifestNativeDeps, installManifestPythonDeps, installPackageFromNpm, installPythonPackages, installPythonRequirements, ipcChildLink, ipcParentLink, isAddonDeploySource, isArrayOutputSchema, isClusterSecretMismatchError, isCollectionArrayMethod, isInfraCapability, isModelDownloaded, isSourceNewer, loadTlsCert, localEndpointPath, localProviderLink, mountNativeCapService, parseCapAction, parseRangeHeader, parseTokenizedUrl, proxyToUpstream, quarantineAddonResidue, readPendingRestart, readinessKey, registerEventBusService, resolveFilePath, resolveHwAccel, resolveNpmInvocation, runNpm, scheduleSelfRestart, scopeKey, scopesAllowDeviceCap, selectAddonResidue, serializeTypedArrays, setHubConnected, setNodeEventInterest, shouldReclaim, startHeapWatch, strandedMb, stripCamstackDeps, subscribePassthrough, udsChildLogToWorkerEntry, validateProviderRegistrations, writePendingRestart };

package/dist/kernel/addon-residue.d.ts

@@ -0,0 +1,49 @@
+/** Where residue is moved to, relative to the addon root. */
+export declare const QUARANTINE_DIRNAME = ".quarantine";
+export type ResidueReason = 
+/** The directory name carries a backup marker — `.bak…`, `.old…`, `.orig…`. */
+'backup-residue'
+/** The directory declares a package whose name is not this directory. */
+ | 'name-mismatch';
+export interface AddonDirCandidate {
+    /** Directory basename under the addon root (or under its `@scope`). */
+    readonly dirName: string;
+    /** `name` from the directory's `package.json`; null when absent/unreadable. */
+    readonly declaredName: string | null;
+}
+export interface ResidueVerdict extends AddonDirCandidate {
+    readonly reason: ResidueReason;
+}
+/**
+ * Is this directory residue? Returns the verdict, or null to keep it.
+ *
+ * A directory with no `package.json` is NOT residue on that ground alone —
+ * `models/`, a half-finished copy, a scratch dir are all absence, not a
+ * rename. Only a backup marker condemns one.
+ */
+export declare function classifyAddonDir(candidate: AddonDirCandidate): ResidueVerdict | null;
+export declare function selectAddonResidue(candidates: readonly AddonDirCandidate[]): readonly ResidueVerdict[];
+export interface QuarantinedEntry extends ResidueVerdict {
+    /** Absolute path the residue occupied under the addon root. */
+    readonly from: string;
+    /** Absolute path it now occupies under `.quarantine/`. */
+    readonly to: string;
+}
+export interface ResidueQuarantineFailure extends ResidueVerdict {
+    readonly from: string;
+    readonly error: string;
+}
+export interface ResidueQuarantineResult {
+    readonly quarantined: readonly QuarantinedEntry[];
+    /** Residue that could not be moved. Reported, never fatal. */
+    readonly failed: readonly ResidueQuarantineFailure[];
+}
+/**
+ * Move every residue directory under `addonsDir` into `addonsDir/.quarantine`.
+ *
+ * Runs at boot, BEFORE anything scans the root or seeds into it — a residue
+ * that is still present when the loader walks has already been installed.
+ * Never throws, never deletes; a move that fails is reported and left in
+ * place, which is strictly better than a half-moved package.
+ */
+export declare function quarantineAddonResidue(addonsDir: string, log: (message: string) => void): ResidueQuarantineResult;

package/dist/kernel/heap-watch.d.ts

@@ -4,6 +4,20 @@ export declare const HEAP_WATCH_INTERVAL_MS = 60000;
 /** Warn above this share of the heap ceiling. Chosen so the warning precedes
  *  the fatal by more than one interval under realistic growth. */
 export declare const HEAP_WATCH_WARN_RATIO = 0.8;
+/**
+ * Reclaim once the process holds this many MB beyond what it is USING.
+ *
+ * Live calibration, both readings from the same hub minutes apart: 2491MB
+ * stranded before the reclaim, 438MB after. 438MB is this process's irreducible
+ * native floor (sqlite pages, libvips, sharp, thread stacks, node's own text) —
+ * collecting against it would buy nothing and cost a stall every minute. 1536
+ * sits clear of that floor and still fires ~1.1GB before the ratchet is worth
+ * anything, so it triggers on the real condition and stops as soon as it is fixed.
+ */
+export declare const HEAP_RECLAIM_TRIGGER_MB = 1536;
+/** Floor on how often the stop-the-world may run. 250-450ms measured, so ten
+ *  minutes keeps the worst case under 0.1% of the router's time. */
+export declare const HEAP_RECLAIM_MIN_INTERVAL_MS = 600000;
 export interface HeapSample {
     readonly rssMb: number;
     readonly heapUsedMb: number;
@@ -27,10 +41,43 @@ export interface HeapWatchSink {
     readonly info: (line: string) => void;
     readonly warn: (line: string) => void;
 }
+/**
+ * RSS the process is holding but not using.
+ *
+ * The subtrahend is heapUSED, not heapTotal, deliberately: the pages V8
+ * committed at a sawtooth peak and no longer needs are counted inside heapTotal,
+ * and they are precisely what this number exists to see.
+ */
+export declare function strandedMb(s: HeapSample): number;
+/** Whether it is worth paying a stop-the-world to get those pages back. */
+export declare function shouldReclaim(s: HeapSample, triggerMb?: number): boolean;
+/** A full collection that also asks V8 to hand the pages back to the OS. */
+export type HeapReclaimer = () => void;
+/**
+ * Build the reclaimer without requiring `--expose-gc` on argv.
+ *
+ * The flag is turned on, the function captured, and the flag turned straight
+ * back off — a global `gc` left reachable by application code is a footgun, and
+ * requiring an argv change would mean this cannot ship without a new image.
+ * Verified against the live hub before being written: 266ms, RSS 1453 -> 1237.
+ *
+ * Returns undefined if V8 declines, so the caller keeps a heartbeat either way.
+ */
+export declare function createV8Reclaimer(): HeapReclaimer | undefined;
+/** Wiring for the reclaim pass. `readMemory`/`heapLimitBytes` exist so a test
+ *  can reach a gigabyte-scale state without allocating one. */
+export interface HeapReclaimOptions {
+    readonly reclaim: HeapReclaimer;
+    readonly readMemory?: () => NodeJS.MemoryUsage;
+    readonly heapLimitBytes?: number;
+    readonly triggerMb?: number;
+    readonly minIntervalMs?: number;
+    readonly now?: () => number;
+}
 /**
  * Start the heartbeat. Returns a stop function.
  *
  * `unref`ed so it can never hold the process open, and every read is wrapped:
  * a diagnostic that can crash the process it watches is worse than none.
  */
-export declare function startHeapWatch(label?: string, sink?: HeapWatchSink, intervalMs?: number): () => void;
+export declare function startHeapWatch(label?: string, sink?: HeapWatchSink, intervalMs?: number, reclaimOptions?: HeapReclaimOptions): () => void;

package/dist/kernel/index.d.ts

@@ -5,6 +5,8 @@ export type { AddonInstallerConfig, InstallSource, InstalledPackage } from './ad
 export { AddonInstaller } from './addon-installer.js';
 export type { AddonInstallSource, AddonManifestEntry, AddonManifestFile } from './addon-manifest.js';
 export { AddonManifest } from './addon-manifest.js';
+export type { AddonDirCandidate, QuarantinedEntry, ResidueQuarantineResult, ResidueReason, ResidueVerdict, } from './addon-residue.js';
+export { QUARANTINE_DIRNAME, classifyAddonDir, quarantineAddonResidue, selectAddonResidue, } from './addon-residue.js';
 export { copyDirRecursive, ensureDir, stripCamstackDeps, copyExtraFileDirs, ensureLibraryBuilt, installPackageFromNpm, isSourceNewer, } from './fs-utils.js';
 export { detectWorkspacePackagesDir } from './workspace-detect.js';
 export { RESTART_MARKER_FILE, clearPendingRestart, getRestartMarkerPath, readPendingRestart, scheduleSelfRestart, writePendingRestart, } from './restart-coordinator.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.60",
+  "version": "1.2.62",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",