@camstack/system 1.2.61 → 1.2.62

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

@@ -1,4 +1,4 @@
-import { Nt as parseJsonObject, f as StorageLocationTypeSchema, it as storageCapability, nt as settingsStoreCapability, pt as BaseAddon } from "../../dist-L6QPJWsr.mjs";
+import { Nt as parseJsonObject, f as StorageLocationTypeSchema, it as storageCapability, nt as settingsStoreCapability, pt as BaseAddon } from "../../dist-DnKpFaP1.mjs";
 import * as path$1 from "node:path";
 import * as fs from "node:fs/promises";
 import { buildStorageLocationRegistry } from "@camstack/system";

package/dist/builtins/system-config/system-config.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BN681PgO.js");
+const require_dist = require("../../dist-DgPUarcs.js");
 //#region src/builtins/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.

package/dist/builtins/system-config/system-config.addon.mjs

@@ -1,4 +1,4 @@
-import { At as hydrateSchema, ft as errMsg, pt as BaseAddon } from "../../dist-L6QPJWsr.mjs";
+import { At as hydrateSchema, ft as errMsg, pt as BaseAddon } from "../../dist-DnKpFaP1.mjs";
 //#region src/builtins/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.

package/dist/builtins/winston-logging/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BN681PgO.js");
+const require_dist = require("../../dist-DgPUarcs.js");
 const require_formatter = require("../../formatter-DqAKDlvN.js");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);

package/dist/builtins/winston-logging/index.mjs

@@ -1,4 +1,4 @@
-import { G as logDestinationCapability, pt as BaseAddon } from "../../dist-L6QPJWsr.mjs";
+import { G as logDestinationCapability, pt as BaseAddon } from "../../dist-DnKpFaP1.mjs";
 import { t as formatLogLine } from "../../formatter-B7qW8bPJ.mjs";
 import * as path$1 from "node:path";
 import path from "node:path";

package/dist/{dist-BN681PgO.js → dist-DgPUarcs.js}

@@ -5434,6 +5434,69 @@ var StreamFormatSchema = zod.z.enum([
 	"mjpeg",
 	"rtsp"
 ]);
+/** A container `produceEventMedia` can emit. */
+var EventMediaKindSchema = zod.z.enum(["mp4", "gif"]);
+/**
+* One produced artifact, referenced by HANDLE.
+*
+* Never inline bytes: a produced clip is 200 KB–5 MB and every consumer of this
+* method is in another runner ([D9](../../../../docs/decisions/adr-0009.md),
+* [D18](../../../../docs/decisions/adr-0018.md) — cross-process media is fetched
+* on demand, compressed, by handle). `bytes` is here so a caller can decide
+* whether it wants the fetch at all.
+*/
+var EventMediaArtifactSchema = zod.z.object({
+	kind: EventMediaKindSchema,
+	/** Opaque, single-camera, short-lived. Redeem with `fetchEventMedia`. */
+	handle: zod.z.string(),
+	/**
+	* The node holding the bytes — the ROUTING key for `fetchEventMedia`.
+	*
+	* `stream-broker` is a singleton cap and an unpinned call never leaves the
+	* hub, so a handle produced on an agent's broker would be redeemed against
+	* the hub's store and come back `null`. Same contract, same field name and
+	* the same reason as `FrameHandleSchema.nodeId`: the producer stamps where it
+	* lives and the consumer pins to it.
+	*/
+	nodeId: zod.z.string(),
+	mime: zod.z.string(),
+	bytes: zod.z.number().int(),
+	width: zod.z.number().int(),
+	height: zod.z.number().int()
+});
+/**
+* What a production actually covered — the answer to the only question an
+* operator asks about a notification clip.
+*
+* `fromTs`/`toTs` are WALL CLOCK, derived from the ring's own packet timeline,
+* so a caller can state "this clip starts 4.1 s before the event" instead of
+* inferring it from a duration. A production whose `fromTs` is later than the
+* event is a production with no pre-roll, and that is exactly the defect this
+* method exists to make visible rather than plausible.
+*/
+var EventMediaCoverageSchema = zod.z.object({
+	fromTs: zod.z.number(),
+	toTs: zod.z.number(),
+	/** Encoded packets in the muxed window. */
+	packets: zod.z.number().int()
+});
+/**
+* The result of ONE cut, in every container the caller asked for.
+*
+* Every artifact in `media` came out of the SAME window of the SAME rendition —
+* that is the whole reason this is one method rather than one call per format.
+* A consumer attaching a gif and a video can no longer show two different
+* moments, because it never chose two sources.
+*/
+var EventMediaProductionSchema = zod.z.object({
+	media: zod.z.array(EventMediaArtifactSchema).readonly(),
+	coverage: EventMediaCoverageSchema,
+	/** The rendition actually cut from — what the default or the fallback chose. */
+	profile: CamProfileSchema,
+	/** `copy` = the camera's own H.264, untouched. `encode` = re-encoded (H.265
+	*  source, a downscale, or a playback rate other than 1). */
+	video: zod.z.enum(["copy", "encode"])
+});
 var RtspRestreamEntrySchema = zod.z.object({
 	brokerId: zod.z.string(),
 	url: zod.z.string(),
@@ -5871,6 +5934,66 @@ var streamBrokerCapability = {
 			kind: "mutation",
 			auth: "admin"
 		}),
+		/**
+		* THE production point for event media — one window, every container.
+		*
+		* `renderPreBufferClip` renders ONE format per call, so a consumer wanting a
+		* gif and a video made two calls and got two windows. On 2026-08-08 the
+		* operator received exactly that: a gif around a doorbell press and an mp4
+		* of the six seconds after it. This method cuts once and derives the rest,
+		* so "the attachments agree" is a property of the service instead of a
+		* discipline every consumer has to keep.
+		*
+		* It is also the only place that owns the packets. The broker already
+		* retains an AnnexB ring per camera (`setClipRetention`, D32) — the
+		* prebuffer — so a production reaches BACKWARDS from the event with no
+		* process to spawn and nothing kept warm. It waits out `postSeconds`, muxes
+		* the window once (COPYING the camera's own H.264 whenever nothing is being
+		* changed), derives any gif from that same mux, and returns HANDLES.
+		*
+		* Intended for every future consumer, not just notifications: a clips API, a
+		* retrain export and an event export all want the same window of the same
+		* camera and must not each grow their own renderer.
+		*/
+		produceEventMedia: method(zod.z.object({
+			deviceId: zod.z.number(),
+			/** Absent = the largest H.264 rendition at or below 1080p, which is
+			*  also the one that can be copied. Falls back to whatever the ring
+			*  actually retained, and the answer says which. */
+			profile: CamProfileSchema.optional(),
+			aroundMs: zod.z.number(),
+			preSeconds: zod.z.number().min(0).max(20).default(4),
+			postSeconds: zod.z.number().min(0).max(20).default(6),
+			kinds: zod.z.array(EventMediaKindSchema).min(1).default(["mp4"]),
+			/** GIF geometry. The video keeps the source's own. */
+			gifMaxWidth: zod.z.number().int().min(120).max(1280).default(640),
+			gifFps: zod.z.number().int().min(1).max(15).default(8),
+			/**
+			* Playback rate, applied to EVERY container so they stay one clip.
+			* `1` is real time and is what allows the copy branch.
+			*/
+			speed: zod.z.number().min(1).max(8).default(1)
+		}), EventMediaProductionSchema, {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
+		* Redeem a {@link EventMediaArtifactSchema} handle for its bytes.
+		*
+		* Separate from the production on purpose (D18): the producing runner keeps
+		* the artifact for a few minutes, and a consumer that only wanted the
+		* coverage never moves a megabyte. `null` once it has expired — a handle is
+		* short-lived by design and a caller that waited too long must see that
+		* rather than a zero-length file.
+		*/
+		fetchEventMedia: method(zod.z.object({ handle: zod.z.string() }), zod.z.object({
+			base64: zod.z.string(),
+			mime: zod.z.string(),
+			bytes: zod.z.number().int()
+		}).nullable(), {
+			kind: "mutation",
+			auth: "admin"
+		}),
 		listAllCameraStreams: method(zod.z.void(), zod.z.array(CameraStreamSchema).readonly()),
 		listAllProfileSlots: method(zod.z.void(), zod.z.array(ProfileSlotSchema).readonly()),
 		getBrokerStats: method(zod.z.object({ brokerId: zod.z.string() }), BrokerStatsSchema),
@@ -31235,6 +31358,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"streamBroker.fetchEventMedia": {
+		capName: "stream-broker",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"streamBroker.getAllRtspEntries": {
 		capName: "stream-broker",
 		capScope: "system",
@@ -31319,6 +31448,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"streamBroker.produceEventMedia": {
+		capName: "stream-broker",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"streamBroker.publishCameraStream": {
 		capName: "stream-broker",
 		capScope: "system",

package/dist/{dist-L6QPJWsr.mjs → dist-DnKpFaP1.mjs}

@@ -5434,6 +5434,69 @@ var StreamFormatSchema = z.enum([
 	"mjpeg",
 	"rtsp"
 ]);
+/** A container `produceEventMedia` can emit. */
+var EventMediaKindSchema = z.enum(["mp4", "gif"]);
+/**
+* One produced artifact, referenced by HANDLE.
+*
+* Never inline bytes: a produced clip is 200 KB–5 MB and every consumer of this
+* method is in another runner ([D9](../../../../docs/decisions/adr-0009.md),
+* [D18](../../../../docs/decisions/adr-0018.md) — cross-process media is fetched
+* on demand, compressed, by handle). `bytes` is here so a caller can decide
+* whether it wants the fetch at all.
+*/
+var EventMediaArtifactSchema = z.object({
+	kind: EventMediaKindSchema,
+	/** Opaque, single-camera, short-lived. Redeem with `fetchEventMedia`. */
+	handle: z.string(),
+	/**
+	* The node holding the bytes — the ROUTING key for `fetchEventMedia`.
+	*
+	* `stream-broker` is a singleton cap and an unpinned call never leaves the
+	* hub, so a handle produced on an agent's broker would be redeemed against
+	* the hub's store and come back `null`. Same contract, same field name and
+	* the same reason as `FrameHandleSchema.nodeId`: the producer stamps where it
+	* lives and the consumer pins to it.
+	*/
+	nodeId: z.string(),
+	mime: z.string(),
+	bytes: z.number().int(),
+	width: z.number().int(),
+	height: z.number().int()
+});
+/**
+* What a production actually covered — the answer to the only question an
+* operator asks about a notification clip.
+*
+* `fromTs`/`toTs` are WALL CLOCK, derived from the ring's own packet timeline,
+* so a caller can state "this clip starts 4.1 s before the event" instead of
+* inferring it from a duration. A production whose `fromTs` is later than the
+* event is a production with no pre-roll, and that is exactly the defect this
+* method exists to make visible rather than plausible.
+*/
+var EventMediaCoverageSchema = z.object({
+	fromTs: z.number(),
+	toTs: z.number(),
+	/** Encoded packets in the muxed window. */
+	packets: z.number().int()
+});
+/**
+* The result of ONE cut, in every container the caller asked for.
+*
+* Every artifact in `media` came out of the SAME window of the SAME rendition —
+* that is the whole reason this is one method rather than one call per format.
+* A consumer attaching a gif and a video can no longer show two different
+* moments, because it never chose two sources.
+*/
+var EventMediaProductionSchema = z.object({
+	media: z.array(EventMediaArtifactSchema).readonly(),
+	coverage: EventMediaCoverageSchema,
+	/** The rendition actually cut from — what the default or the fallback chose. */
+	profile: CamProfileSchema,
+	/** `copy` = the camera's own H.264, untouched. `encode` = re-encoded (H.265
+	*  source, a downscale, or a playback rate other than 1). */
+	video: z.enum(["copy", "encode"])
+});
 var RtspRestreamEntrySchema = z.object({
 	brokerId: z.string(),
 	url: z.string(),
@@ -5871,6 +5934,66 @@ var streamBrokerCapability = {
 			kind: "mutation",
 			auth: "admin"
 		}),
+		/**
+		* THE production point for event media — one window, every container.
+		*
+		* `renderPreBufferClip` renders ONE format per call, so a consumer wanting a
+		* gif and a video made two calls and got two windows. On 2026-08-08 the
+		* operator received exactly that: a gif around a doorbell press and an mp4
+		* of the six seconds after it. This method cuts once and derives the rest,
+		* so "the attachments agree" is a property of the service instead of a
+		* discipline every consumer has to keep.
+		*
+		* It is also the only place that owns the packets. The broker already
+		* retains an AnnexB ring per camera (`setClipRetention`, D32) — the
+		* prebuffer — so a production reaches BACKWARDS from the event with no
+		* process to spawn and nothing kept warm. It waits out `postSeconds`, muxes
+		* the window once (COPYING the camera's own H.264 whenever nothing is being
+		* changed), derives any gif from that same mux, and returns HANDLES.
+		*
+		* Intended for every future consumer, not just notifications: a clips API, a
+		* retrain export and an event export all want the same window of the same
+		* camera and must not each grow their own renderer.
+		*/
+		produceEventMedia: method(z.object({
+			deviceId: z.number(),
+			/** Absent = the largest H.264 rendition at or below 1080p, which is
+			*  also the one that can be copied. Falls back to whatever the ring
+			*  actually retained, and the answer says which. */
+			profile: CamProfileSchema.optional(),
+			aroundMs: z.number(),
+			preSeconds: z.number().min(0).max(20).default(4),
+			postSeconds: z.number().min(0).max(20).default(6),
+			kinds: z.array(EventMediaKindSchema).min(1).default(["mp4"]),
+			/** GIF geometry. The video keeps the source's own. */
+			gifMaxWidth: z.number().int().min(120).max(1280).default(640),
+			gifFps: z.number().int().min(1).max(15).default(8),
+			/**
+			* Playback rate, applied to EVERY container so they stay one clip.
+			* `1` is real time and is what allows the copy branch.
+			*/
+			speed: z.number().min(1).max(8).default(1)
+		}), EventMediaProductionSchema, {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
+		* Redeem a {@link EventMediaArtifactSchema} handle for its bytes.
+		*
+		* Separate from the production on purpose (D18): the producing runner keeps
+		* the artifact for a few minutes, and a consumer that only wanted the
+		* coverage never moves a megabyte. `null` once it has expired — a handle is
+		* short-lived by design and a caller that waited too long must see that
+		* rather than a zero-length file.
+		*/
+		fetchEventMedia: method(z.object({ handle: z.string() }), z.object({
+			base64: z.string(),
+			mime: z.string(),
+			bytes: z.number().int()
+		}).nullable(), {
+			kind: "mutation",
+			auth: "admin"
+		}),
 		listAllCameraStreams: method(z.void(), z.array(CameraStreamSchema).readonly()),
 		listAllProfileSlots: method(z.void(), z.array(ProfileSlotSchema).readonly()),
 		getBrokerStats: method(z.object({ brokerId: z.string() }), BrokerStatsSchema),
@@ -31235,6 +31358,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"streamBroker.fetchEventMedia": {
+		capName: "stream-broker",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"streamBroker.getAllRtspEntries": {
 		capName: "stream-broker",
 		capScope: "system",
@@ -31319,6 +31448,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"streamBroker.produceEventMedia": {
+		capName: "stream-broker",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"streamBroker.publishCameraStream": {
 		capName: "stream-broker",
 		capScope: "system",

package/dist/index.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("./chunk-Cek0wNdY.js");
-const require_dist = require("./dist-BN681PgO.js");
+const require_dist = require("./dist-DgPUarcs.js");
 const require_model_download_service = require("./model-download-service-Cpc6SWzV.js");
 const require_manifest_python_deps = require("./manifest-python-deps-d4acYXVV.js");
 const require_resource_monitor = require("./resource-monitor-DNNomR-i.js");
@@ -3356,7 +3356,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 node_fs.statSync(p).isDirectory();
 	} catch {
@@ -3490,10 +3495,10 @@ var AddonManifest = class {
 		/** Package name → version, for every ADDON package actually installed. */
 		const onDisk = /* @__PURE__ */ new Map();
 		for (const scope of node_fs.readdirSync(addonsDir, { withFileTypes: true })) {
-			if (!scope.name.startsWith("@") || !isDirLike(node_path.join(addonsDir, scope.name))) continue;
+			if (!scope.name.startsWith("@") || !isDirLike$1(node_path.join(addonsDir, scope.name))) continue;
 			const scopeDir = node_path.join(addonsDir, scope.name);
 			for (const pkg of node_fs.readdirSync(scopeDir, { withFileTypes: true })) {
-				if (!isDirLike(node_path.join(scopeDir, pkg.name))) continue;
+				if (!isDirLike$1(node_path.join(scopeDir, pkg.name))) continue;
 				const pkgJsonPath = node_path.join(scopeDir, pkg.name, "package.json");
 				if (!node_fs.existsSync(pkgJsonPath)) continue;
 				let pkgJson;
@@ -3507,6 +3512,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);
 			}
 		}
@@ -5024,6 +5030,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(node_fs.readFileSync(node_path.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(node_fs.readFileSync(node_path.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 node_fs.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 = node_path.join(store, base);
+	let n = 1;
+	while (node_fs.existsSync(candidate)) {
+		candidate = node_path.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 (!node_fs.existsSync(addonsDir)) return {
+		quarantined,
+		failed
+	};
+	const store = node_path.join(addonsDir, QUARANTINE_DIRNAME);
+	const scan = (parent, scope) => {
+		let names;
+		try {
+			names = node_fs.readdirSync(parent);
+		} catch {
+			return;
+		}
+		for (const dirName of names) {
+			const full = node_path.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 {
+				node_fs.mkdirSync(store, { recursive: true });
+				node_fs.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.
@@ -94723,6 +94922,7 @@ Object.defineProperty(exports, "PYTHON_VERSION", {
 exports.PipelineRunner = PipelineRunner;
 exports.PipelineValidator = PipelineValidator;
 exports.PythonEnvManager = PythonEnvManager;
+exports.QUARANTINE_DIRNAME = QUARANTINE_DIRNAME;
 exports.RESTART_MARKER_FILE = RESTART_MARKER_FILE;
 exports.RUNTIME_DEFAULTS = require_dist.RUNTIME_DEFAULTS;
 exports.ReadinessRegistry = require_dist.ReadinessRegistry;
@@ -94775,6 +94975,7 @@ exports.capActionName = require_manifest_python_deps.capActionName;
 exports.capActionSuffix = require_manifest_python_deps.capActionSuffix;
 exports.capBareAction = require_manifest_python_deps.capBareAction;
 exports.capServiceName = require_manifest_python_deps.capServiceName;
+exports.classifyAddonDir = classifyAddonDir;
 exports.classifyCapRoute = require_manifest_python_deps.classifyCapRoute;
 exports.clearPendingRestart = clearPendingRestart;
 exports.clusterEventTopic = require_manifest_python_deps.clusterEventTopic;
@@ -94916,6 +95117,7 @@ exports.parseCapAction = require_manifest_python_deps.parseCapAction;
 exports.parseRangeHeader = require_model_download_service.parseRangeHeader;
 exports.parseTokenizedUrl = require_model_download_service.parseTokenizedUrl;
 exports.proxyToUpstream = proxyToUpstream;
+exports.quarantineAddonResidue = quarantineAddonResidue;
 exports.readPendingRestart = readPendingRestart;
 exports.readinessKey = require_dist.readinessKey;
 exports.registerEventBusService = require_manifest_python_deps.registerEventBusService;
@@ -94926,6 +95128,7 @@ exports.runNpm = require_manifest_python_deps.runNpm;
 exports.scheduleSelfRestart = scheduleSelfRestart;
 exports.scopeKey = require_dist.scopeKey;
 exports.scopesAllowDeviceCap = scopesAllowDeviceCap;
+exports.selectAddonResidue = selectAddonResidue;
 exports.serializeTypedArrays = require_manifest_python_deps.serializeTypedArrays;
 exports.setHubConnected = require_manifest_python_deps.setHubConnected;
 exports.setNodeEventInterest = require_manifest_python_deps.setNodeEventInterest;