@camstack/system 1.2.110 → 1.2.111

package/dist/addon-runner.js

@@ -1,5 +1,5 @@
 const require_chunk = require("./chunk-Cek0wNdY.js");
-const require_manifest_python_deps = require("./manifest-python-deps-GejnH--L.js");
+const require_manifest_python_deps = require("./manifest-python-deps-MA_BZGBz.js");
 const require_custom_action_registry = require("./custom-action-registry-jY0NOZK8.js");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);

package/dist/addon-runner.mjs

@@ -1,4 +1,4 @@
-import { I as createUdsLoggerWithControl, L as LocalChildClient, Pt as startRunnerHeapWatch, at as setWorkerNativeCapsChangeListener, bt as installManifestNativeDeps, i as createUdsAddonContext, nt as getWorkerNativeCapProvider, rt as getWorkerNativeCapSnapshot, st as validateProviderRegistrations, t as installManifestPythonDeps, xt as resolveAddonClass } from "./manifest-python-deps-5ei2xVUh.mjs";
+import { I as createUdsLoggerWithControl, L as LocalChildClient, Pt as startRunnerHeapWatch, at as setWorkerNativeCapsChangeListener, bt as installManifestNativeDeps, i as createUdsAddonContext, nt as getWorkerNativeCapProvider, rt as getWorkerNativeCapSnapshot, st as validateProviderRegistrations, t as installManifestPythonDeps, xt as resolveAddonClass } from "./manifest-python-deps-Cb1ANt3i.mjs";
 import { t as CustomActionRegistry } from "./custom-action-registry-F__gp_VX.mjs";
 import { register } from "node:module";
 import * as path$1 from "node:path";

package/dist/index.js

@@ -25,7 +25,7 @@ const require_builtins_system_config_system_config_addon = require("./builtins/s
 require("./builtins/system-config/index.js");
 const require_builtins_winston_logging_index = require("./builtins/winston-logging/index.js");
 const require_file_data_plane = require("./file-data-plane-DUHPHa-Y.js");
-const require_manifest_python_deps = require("./manifest-python-deps-GejnH--L.js");
+const require_manifest_python_deps = require("./manifest-python-deps-MA_BZGBz.js");
 const require_resource_monitor = require("./resource-monitor-CdnzxBLP.js");
 const require_custom_action_registry = require("./custom-action-registry-jY0NOZK8.js");
 let zod = require("zod");
@@ -5367,6 +5367,7 @@ var CapabilityRegistry = class CapabilityRegistry {
 		const state = {
 			definition,
 			providers: /* @__PURE__ */ new Map(),
+			providerOwners: /* @__PURE__ */ new Map(),
 			activeAddonId: null,
 			router: null,
 			disabledProviders: /* @__PURE__ */ new Set()
@@ -5424,8 +5425,15 @@ var CapabilityRegistry = class CapabilityRegistry {
 	* Double-register of the same pair is always a programmer error —
 	* two legitimately different addons implementing the same cap keep
 	* using different `addonId`s and the user picks one via `configReader`.
-	*/
-	registerProvider(capabilityName, addonId, provider) {
+	*
+	* `owner` (optional) stamps the registration with the incarnation that made
+	* it — see {@link ProviderOwnerToken}. Once stamped, only an unregister
+	* presenting the SAME token can delete it. Registration paths whose key is
+	* reused across process generations (the UDS child manifest, the D3
+	* `registerNode` handshake) MUST pass one; ownerless registrations keep the
+	* historical unconditional behaviour.
+	*/
+	registerProvider(capabilityName, addonId, provider, owner) {
 		let state = this.capabilities.get(capabilityName);
 		if (!state) {
 			const colonIdx = capabilityName.indexOf(":");
@@ -5457,6 +5465,7 @@ var CapabilityRegistry = class CapabilityRegistry {
 			if (missing.length > 0) throw new Error(`CapabilityRegistry: provider "${addonId}" for capability "${capabilityName}" declares exposesDeviceSettings: true but is missing DeviceSettingsContribution method(s): ${missing.join(", ")}. Implement them on the provider (or drop the flag from the cap def).`);
 		}
 		state.providers.set(addonId, provider);
+		if (owner !== void 0) state.providerOwners.set(addonId, owner);
 		if (state.definition.mode === "singleton") {
 			const userChoice = this.configReader?.(capabilityName);
 			const preferred = state.definition.preferredProvider;
@@ -5487,7 +5496,8 @@ var CapabilityRegistry = class CapabilityRegistry {
 			tags: { addonId },
 			meta: {
 				capability: capabilityName,
-				mode: state.definition.mode
+				mode: state.definition.mode,
+				...owner === void 0 ? {} : { owner }
 			}
 		});
 		this.emitEvent("capability:provider-registered", {
@@ -5534,11 +5544,70 @@ var CapabilityRegistry = class CapabilityRegistry {
 		const declarers = this.manifestDeclarers.get(capabilityName);
 		return declarers ? [...declarers] : [];
 	}
-	/** Unregister a provider. For singleton: clears active. For collection: removes from list. */
-	unregisterProvider(capabilityName, addonId) {
+	/**
+	* The owner token a registration declared, or `null` when the pair is not
+	* registered or was registered without one.
+	*/
+	getProviderOwner(capabilityName, addonId) {
+		return this.capabilities.get(capabilityName)?.providerOwners.get(addonId) ?? null;
+	}
+	/**
+	* Hand an EXISTING registration to a new owner, without touching the provider
+	* instance, the active-singleton selection or any event.
+	*
+	* The takeover case: a replacement runner handshakes with an UNCHANGED cap
+	* set, so the manifest diff correctly leaves the registration alone — but the
+	* registration is still stamped with the dead generation's token, and nothing
+	* the LIVE generation can present would ever match it. Re-stamping keeps the
+	* capability cleanable when the successor eventually dies.
+	*
+	* Returns `false` when the pair is not registered (nothing to hand over) —
+	* the caller decides whether that is a register-instead or a diagnosis.
+	*/
+	reassignProviderOwner(capabilityName, addonId, owner) {
+		const state = this.capabilities.get(capabilityName);
+		if (!state || !state.providers.has(addonId)) return false;
+		const previous = state.providerOwners.get(addonId);
+		if (previous === owner) return true;
+		state.providerOwners.set(addonId, owner);
+		this.logger.info("Capability registration ownership reassigned", {
+			tags: { addonId },
+			meta: {
+				capability: capabilityName,
+				owner,
+				previousOwner: previous ?? null
+			}
+		});
+		return true;
+	}
+	/**
+	* Unregister a provider. For singleton: clears active. For collection:
+	* removes from list.
+	*
+	* `owner` is the caller's PROOF that it owns the registration it is deleting.
+	* When the registration declared an owner (see {@link ProviderOwnerToken})
+	* and the caller presents a different one — or none at all — this is a
+	* logged no-op: the caller belongs to a generation that no longer holds the
+	* key. This is what stops a dead runner's teardown from erasing its
+	* successor's live registration ([D188](../../../../docs/decisions/adr-0188-an-unregister-carries-proof-of-ownership.md)).
+	*/
+	unregisterProvider(capabilityName, addonId, owner) {
 		const state = this.capabilities.get(capabilityName);
 		if (!state) return;
+		const registeredOwner = state.providerOwners.get(addonId);
+		if (registeredOwner !== void 0 && registeredOwner !== owner) {
+			this.logger.info("Unregister ignored — registration is owned by another incarnation", {
+				tags: { addonId },
+				meta: {
+					capability: capabilityName,
+					registeredOwner,
+					presentedOwner: owner ?? null
+				}
+			});
+			return;
+		}
 		state.providers.delete(addonId);
+		state.providerOwners.delete(addonId);
 		if (state.definition.mode === "singleton" && state.activeAddonId === addonId) {
 			const userChoice = this.configReader?.(capabilityName);
 			const preferred = state.definition.preferredProvider;
@@ -94555,6 +94624,11 @@ var JobJournal = class {
 function safeSegment(name) {
 	return name.replace(/[^a-zA-Z0-9._-]/g, "_");
 }
+/** An exact semver — the only shape the staged package.json can be compared
+*  against literally. Anything else ('latest', 'beta', a range) is a dist-tag
+*  the FETCHER resolves; comparing the resolved version to the literal tag
+*  failed every tag-based update (30/30 on 2026-08-20). */
+var EXACT_SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 var StagingArea = class {
 	stagingDir;
 	deps;
@@ -94572,8 +94646,12 @@ var StagingArea = class {
 		if (input.signal.aborted) throw new Error("staging aborted after fetch");
 		await this.deps.extract(tgz, destDir);
 		const raw = JSON.parse(node_fs.readFileSync(node_path.join(destDir, "package.json"), "utf-8"));
-		if (raw.version !== input.version) throw new Error(`staging validation failed: ${input.name} expected version ${input.version}, got ${String(raw.version)}`);
-		return { stagedPath: destDir };
+		if (typeof raw.version !== "string" || raw.version.length === 0) throw new Error(`staging validation failed: ${input.name} staged a package.json with no version`);
+		if (EXACT_SEMVER.test(input.version) && raw.version !== input.version) throw new Error(`staging validation failed: ${input.name} expected version ${input.version}, got ${raw.version}`);
+		return {
+			stagedPath: destDir,
+			resolvedVersion: raw.version
+		};
 	}
 	cleanup(jobId) {
 		node_fs.rmSync(node_path.join(this.stagingDir, jobId), {

package/dist/index.mjs

@@ -24,7 +24,7 @@ import { SystemConfigAddon } from "./builtins/system-config/system-config.addon.
 import "./builtins/system-config/index.mjs";
 import { WinstonDestination, WinstonLoggingAddon } from "./builtins/winston-logging/index.mjs";
 import { a as parseTokenizedUrl, c as collectModelFiles, d as downloadModel, f as ensureModel, h as isModelDownloaded, i as parseRangeHeader, l as deleteModelFromDisk, m as getModelFilePath, n as contentTypeFor, o as resolveFilePath, p as fetchJson, r as createAuthenticatedFileServer, s as ModelDownloadService, t as createFileDataPlaneHandler, u as downloadFile } from "./file-data-plane-CuE_hBli.mjs";
-import { $ as buildNativeCapProxy, A as createHubCapForwardService, At as buildHeapSample, B as AGENT_CAP_FWD_ACTION, C as brokerTransportLink, Ct as runNpm, D as localProviderLink, Dt as HEAP_WATCH_INTERVAL_MS, E as ipcParentLink, Et as HEAP_RECLAIM_TRIGGER_MB, F as createUdsLogger, Ft as strandedMb, G as callWithServiceDiscovery, H as CapRouteResolver, I as createUdsLoggerWithControl, J as UdsLocalTransportServer, K as createLocalTransport, L as LocalChildClient, M as createUdsEventBridge, Mt as shouldReclaim, N as createUdsEventBus, Nt as startHeapWatch, O as HUB_CAP_FWD_ACTION, Ot as HEAP_WATCH_WARN_RATIO, P as udsChildLogToWorkerEntry, Pt as startRunnerHeapWatch, Q as encodeFrame, R as LocalChildRegistry, S as brokerCallForCap, St as resolveNpmInvocation, T as ipcChildLink, Tt as HEAP_RECLAIM_MIN_INTERVAL_MS, 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, jt as createV8Reclaimer, k as HUB_CAP_FWD_SERVICE, kt as RUNNER_HEAP_WATCH_INTERVAL_MS, 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 resolveAddonClass, y as CapUsageRegistry, yt as copyBundledNativeModules, z as UDS_NO_ROUTE_PREFIX } from "./manifest-python-deps-5ei2xVUh.mjs";
+import { $ as buildNativeCapProxy, A as createHubCapForwardService, At as buildHeapSample, B as AGENT_CAP_FWD_ACTION, C as brokerTransportLink, Ct as runNpm, D as localProviderLink, Dt as HEAP_WATCH_INTERVAL_MS, E as ipcParentLink, Et as HEAP_RECLAIM_TRIGGER_MB, F as createUdsLogger, Ft as strandedMb, G as callWithServiceDiscovery, H as CapRouteResolver, I as createUdsLoggerWithControl, J as UdsLocalTransportServer, K as createLocalTransport, L as LocalChildClient, M as createUdsEventBridge, Mt as shouldReclaim, N as createUdsEventBus, Nt as startHeapWatch, O as HUB_CAP_FWD_ACTION, Ot as HEAP_WATCH_WARN_RATIO, P as udsChildLogToWorkerEntry, Pt as startRunnerHeapWatch, Q as encodeFrame, R as LocalChildRegistry, S as brokerCallForCap, St as resolveNpmInvocation, T as ipcChildLink, Tt as HEAP_RECLAIM_MIN_INTERVAL_MS, 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, jt as createV8Reclaimer, k as HUB_CAP_FWD_SERVICE, kt as RUNNER_HEAP_WATCH_INTERVAL_MS, 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 resolveAddonClass, y as CapUsageRegistry, yt as copyBundledNativeModules, z as UDS_NO_ROUTE_PREFIX } from "./manifest-python-deps-Cb1ANt3i.mjs";
 import { n as getSinglePidStats, t as getPidStats } from "./resource-monitor-BWmQ5i-o.mjs";
 import { t as CustomActionRegistry } from "./custom-action-registry-F__gp_VX.mjs";
 import { z } from "zod";
@@ -5360,6 +5360,7 @@ var CapabilityRegistry = class CapabilityRegistry {
 		const state = {
 			definition,
 			providers: /* @__PURE__ */ new Map(),
+			providerOwners: /* @__PURE__ */ new Map(),
 			activeAddonId: null,
 			router: null,
 			disabledProviders: /* @__PURE__ */ new Set()
@@ -5417,8 +5418,15 @@ var CapabilityRegistry = class CapabilityRegistry {
 	* Double-register of the same pair is always a programmer error —
 	* two legitimately different addons implementing the same cap keep
 	* using different `addonId`s and the user picks one via `configReader`.
-	*/
-	registerProvider(capabilityName, addonId, provider) {
+	*
+	* `owner` (optional) stamps the registration with the incarnation that made
+	* it — see {@link ProviderOwnerToken}. Once stamped, only an unregister
+	* presenting the SAME token can delete it. Registration paths whose key is
+	* reused across process generations (the UDS child manifest, the D3
+	* `registerNode` handshake) MUST pass one; ownerless registrations keep the
+	* historical unconditional behaviour.
+	*/
+	registerProvider(capabilityName, addonId, provider, owner) {
 		let state = this.capabilities.get(capabilityName);
 		if (!state) {
 			const colonIdx = capabilityName.indexOf(":");
@@ -5450,6 +5458,7 @@ var CapabilityRegistry = class CapabilityRegistry {
 			if (missing.length > 0) throw new Error(`CapabilityRegistry: provider "${addonId}" for capability "${capabilityName}" declares exposesDeviceSettings: true but is missing DeviceSettingsContribution method(s): ${missing.join(", ")}. Implement them on the provider (or drop the flag from the cap def).`);
 		}
 		state.providers.set(addonId, provider);
+		if (owner !== void 0) state.providerOwners.set(addonId, owner);
 		if (state.definition.mode === "singleton") {
 			const userChoice = this.configReader?.(capabilityName);
 			const preferred = state.definition.preferredProvider;
@@ -5480,7 +5489,8 @@ var CapabilityRegistry = class CapabilityRegistry {
 			tags: { addonId },
 			meta: {
 				capability: capabilityName,
-				mode: state.definition.mode
+				mode: state.definition.mode,
+				...owner === void 0 ? {} : { owner }
 			}
 		});
 		this.emitEvent("capability:provider-registered", {
@@ -5527,11 +5537,70 @@ var CapabilityRegistry = class CapabilityRegistry {
 		const declarers = this.manifestDeclarers.get(capabilityName);
 		return declarers ? [...declarers] : [];
 	}
-	/** Unregister a provider. For singleton: clears active. For collection: removes from list. */
-	unregisterProvider(capabilityName, addonId) {
+	/**
+	* The owner token a registration declared, or `null` when the pair is not
+	* registered or was registered without one.
+	*/
+	getProviderOwner(capabilityName, addonId) {
+		return this.capabilities.get(capabilityName)?.providerOwners.get(addonId) ?? null;
+	}
+	/**
+	* Hand an EXISTING registration to a new owner, without touching the provider
+	* instance, the active-singleton selection or any event.
+	*
+	* The takeover case: a replacement runner handshakes with an UNCHANGED cap
+	* set, so the manifest diff correctly leaves the registration alone — but the
+	* registration is still stamped with the dead generation's token, and nothing
+	* the LIVE generation can present would ever match it. Re-stamping keeps the
+	* capability cleanable when the successor eventually dies.
+	*
+	* Returns `false` when the pair is not registered (nothing to hand over) —
+	* the caller decides whether that is a register-instead or a diagnosis.
+	*/
+	reassignProviderOwner(capabilityName, addonId, owner) {
+		const state = this.capabilities.get(capabilityName);
+		if (!state || !state.providers.has(addonId)) return false;
+		const previous = state.providerOwners.get(addonId);
+		if (previous === owner) return true;
+		state.providerOwners.set(addonId, owner);
+		this.logger.info("Capability registration ownership reassigned", {
+			tags: { addonId },
+			meta: {
+				capability: capabilityName,
+				owner,
+				previousOwner: previous ?? null
+			}
+		});
+		return true;
+	}
+	/**
+	* Unregister a provider. For singleton: clears active. For collection:
+	* removes from list.
+	*
+	* `owner` is the caller's PROOF that it owns the registration it is deleting.
+	* When the registration declared an owner (see {@link ProviderOwnerToken})
+	* and the caller presents a different one — or none at all — this is a
+	* logged no-op: the caller belongs to a generation that no longer holds the
+	* key. This is what stops a dead runner's teardown from erasing its
+	* successor's live registration ([D188](../../../../docs/decisions/adr-0188-an-unregister-carries-proof-of-ownership.md)).
+	*/
+	unregisterProvider(capabilityName, addonId, owner) {
 		const state = this.capabilities.get(capabilityName);
 		if (!state) return;
+		const registeredOwner = state.providerOwners.get(addonId);
+		if (registeredOwner !== void 0 && registeredOwner !== owner) {
+			this.logger.info("Unregister ignored — registration is owned by another incarnation", {
+				tags: { addonId },
+				meta: {
+					capability: capabilityName,
+					registeredOwner,
+					presentedOwner: owner ?? null
+				}
+			});
+			return;
+		}
 		state.providers.delete(addonId);
+		state.providerOwners.delete(addonId);
 		if (state.definition.mode === "singleton" && state.activeAddonId === addonId) {
 			const userChoice = this.configReader?.(capabilityName);
 			const preferred = state.definition.preferredProvider;
@@ -94548,6 +94617,11 @@ var JobJournal = class {
 function safeSegment(name) {
 	return name.replace(/[^a-zA-Z0-9._-]/g, "_");
 }
+/** An exact semver — the only shape the staged package.json can be compared
+*  against literally. Anything else ('latest', 'beta', a range) is a dist-tag
+*  the FETCHER resolves; comparing the resolved version to the literal tag
+*  failed every tag-based update (30/30 on 2026-08-20). */
+var EXACT_SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 var StagingArea = class {
 	stagingDir;
 	deps;
@@ -94565,8 +94639,12 @@ var StagingArea = class {
 		if (input.signal.aborted) throw new Error("staging aborted after fetch");
 		await this.deps.extract(tgz, destDir);
 		const raw = JSON.parse(fs$17.readFileSync(path$39.join(destDir, "package.json"), "utf-8"));
-		if (raw.version !== input.version) throw new Error(`staging validation failed: ${input.name} expected version ${input.version}, got ${String(raw.version)}`);
-		return { stagedPath: destDir };
+		if (typeof raw.version !== "string" || raw.version.length === 0) throw new Error(`staging validation failed: ${input.name} staged a package.json with no version`);
+		if (EXACT_SEMVER.test(input.version) && raw.version !== input.version) throw new Error(`staging validation failed: ${input.name} expected version ${input.version}, got ${raw.version}`);
+		return {
+			stagedPath: destDir,
+			resolvedVersion: raw.version
+		};
 	}
 	cleanup(jobId) {
 		fs$17.rmSync(path$39.join(this.stagingDir, jobId), {

package/dist/kernel/capability-registry.d.ts

@@ -19,6 +19,18 @@ export type ConfigReader = (capability: string) => string | undefined;
  * {@link ConfigReader} does for singletons.
  */
 export type CollectionConfigReader = (capability: string) => readonly string[] | undefined;
+/**
+ * Proof that an unregister owns the registration it is about to delete.
+ *
+ * A `(capability, addonId)` key is NOT unique over time: a runner replaced by
+ * an update re-registers under the exact same key (`resolveRunnerId` is
+ * deterministic), so the dead generation's teardown and the live generation's
+ * registration are indistinguishable by key alone. The owner token names the
+ * INCARNATION that made a registration — e.g. `hub/recorder#7` — and
+ * {@link CapabilityRegistry.unregisterProvider} refuses any unregister that
+ * cannot present it. See docs/decisions/adr-0188-an-unregister-carries-proof-of-ownership.md.
+ */
+export type ProviderOwnerToken = string;
 export declare class CapabilityRegistry {
     private readonly capabilities;
     private readonly logger;
@@ -148,8 +160,15 @@ export declare class CapabilityRegistry {
      * Double-register of the same pair is always a programmer error —
      * two legitimately different addons implementing the same cap keep
      * using different `addonId`s and the user picks one via `configReader`.
+     *
+     * `owner` (optional) stamps the registration with the incarnation that made
+     * it — see {@link ProviderOwnerToken}. Once stamped, only an unregister
+     * presenting the SAME token can delete it. Registration paths whose key is
+     * reused across process generations (the UDS child manifest, the D3
+     * `registerNode` handshake) MUST pass one; ownerless registrations keep the
+     * historical unconditional behaviour.
      */
-    registerProvider(capabilityName: string, addonId: string, provider: unknown): void;
+    registerProvider(capabilityName: string, addonId: string, provider: unknown, owner?: ProviderOwnerToken): void;
     /**
      * Whether a provider for the exact `(capabilityName, addonId)` pair is
      * currently registered. Lets a re-registration path (e.g. the agent's
@@ -173,8 +192,37 @@ export declare class CapabilityRegistry {
      * it is the diagnosis).
      */
     getManifestDeclarers(capabilityName: string): readonly string[];
-    /** Unregister a provider. For singleton: clears active. For collection: removes from list. */
-    unregisterProvider(capabilityName: string, addonId: string): void;
+    /**
+     * The owner token a registration declared, or `null` when the pair is not
+     * registered or was registered without one.
+     */
+    getProviderOwner(capabilityName: string, addonId: string): ProviderOwnerToken | null;
+    /**
+     * Hand an EXISTING registration to a new owner, without touching the provider
+     * instance, the active-singleton selection or any event.
+     *
+     * The takeover case: a replacement runner handshakes with an UNCHANGED cap
+     * set, so the manifest diff correctly leaves the registration alone — but the
+     * registration is still stamped with the dead generation's token, and nothing
+     * the LIVE generation can present would ever match it. Re-stamping keeps the
+     * capability cleanable when the successor eventually dies.
+     *
+     * Returns `false` when the pair is not registered (nothing to hand over) —
+     * the caller decides whether that is a register-instead or a diagnosis.
+     */
+    reassignProviderOwner(capabilityName: string, addonId: string, owner: ProviderOwnerToken): boolean;
+    /**
+     * Unregister a provider. For singleton: clears active. For collection:
+     * removes from list.
+     *
+     * `owner` is the caller's PROOF that it owns the registration it is deleting.
+     * When the registration declared an owner (see {@link ProviderOwnerToken})
+     * and the caller presents a different one — or none at all — this is a
+     * logged no-op: the caller belongs to a generation that no longer holds the
+     * key. This is what stops a dead runner's teardown from erasing its
+     * successor's live registration ([D188](../../../../docs/decisions/adr-0188-an-unregister-carries-proof-of-ownership.md)).
+     */
+    unregisterProvider(capabilityName: string, addonId: string, owner?: ProviderOwnerToken): void;
     /** Enable a previously disabled collection provider. */
     enableCollectionProvider(capability: string, addonId: string): void;
     /** Disable a collection provider (keeps it registered but excluded from active list). */

package/dist/kernel/index.d.ts

@@ -17,7 +17,7 @@ export { buildCapRouters, builderMountedCapNames } from './cap-router-builder.js
 export type { CapRouterPrimitives, CapRouterServices, CapProviderGetter, RemoteProxyFactory, ProcedureBuilder, ProcedureResolverArgs, } from './cap-router-builder.js';
 export { describeProviderKindDrift } from './provider-kind-drift.js';
 export type { ProviderKindHint } from './provider-kind-drift.js';
-export type { CapabilityRouter, CapabilityRouterFactory, ConfigReader, } from './capability-registry.js';
+export type { CapabilityRouter, CapabilityRouterFactory, ConfigReader, ProviderOwnerToken, } from './capability-registry.js';
 export { CustomActionRegistry, type CustomActionEntry } from './custom-action-registry.js';
 export { INFRA_CAPABILITIES, isInfraCapability } from './infra-capabilities.js';
 export type { InfraCapability } from './infra-capabilities.js';

package/dist/kernel/lifecycle/staging-area.d.ts

@@ -16,6 +16,7 @@ export declare class StagingArea {
     constructor(stagingDir: string, deps: StagingAreaDeps);
     fetchAndStage(input: FetchAndStageInput): Promise<{
         stagedPath: string;
+        resolvedVersion: string;
     }>;
     cleanup(jobId: string): void;
     /**

package/dist/kernel/transport/child-cap-protocol.d.ts

@@ -222,6 +222,18 @@ export type ParentToChildRequest = CapCallMessage | ParentEventMessage | Readine
 export interface RegisteredChild {
     readonly childId: string;
     readonly caps: readonly ChildCapDescriptor[];
+    /**
+     * Monotonic id of the CONNECTION this registration arrived on, unique within
+     * the parent process.
+     *
+     * `childId` is deterministic (`resolveRunnerId`), so a runner replaced by an
+     * update reconnects under the exact same id — the two generations are
+     * indistinguishable without this. Consumers stamp it onto whatever they
+     * derive from the child (capability registrations, subtree manifests) so a
+     * teardown arriving from the DEAD generation can be told apart from the live
+     * one. See docs/decisions/adr-0188-an-unregister-carries-proof-of-ownership.md.
+     */
+    readonly incarnation: number;
 }
 /** Arguments to route a cap method call (the `cap-call` message minus its discriminant). */
 export type CapCallInput = Omit<CapCallMessage, 'kind'>;

package/dist/kernel/transport/local-child-registry.d.ts

@@ -139,6 +139,8 @@ export declare class LocalChildRegistry {
     private readonly children;
     private registeredHandler;
     private goneHandler;
+    /** Source of {@link RegisteredChild.incarnation}; one bump per accepted connection. */
+    private nextIncarnation;
     private eventHandler;
     private logHandler;
     private readinessHandler;
@@ -291,8 +293,13 @@ export declare class LocalChildRegistry {
     listChildren(): readonly RegisteredChild[];
     /** Register the (single) child-registered handler. Only one handler is active at a time. */
     onChildRegistered(handler: (child: RegisteredChild) => void): void;
-    /** Register the (single) child-gone handler. Only one handler is active at a time. */
-    onChildGone(handler: (childId: string) => void): void;
+    /**
+     * Register the (single) child-gone handler. Only one handler is active at a
+     * time. The handler receives the {@link RegisteredChild.incarnation} of the
+     * connection that closed — carry it into whatever teardown it triggers, so a
+     * dead generation cannot tear down its successor's work.
+     */
+    onChildGone(handler: (childId: string, incarnation: number) => void): void;
     /**
      * Register the (single) child-event handler. Invoked when a child sends an
      * event via `LocalChildClient.emitEvent`. Only one handler is active at a

package/dist/{manifest-python-deps-5ei2xVUh.mjs → manifest-python-deps-Cb1ANt3i.mjs}

@@ -4832,6 +4832,8 @@ var LocalChildRegistry = class {
 	children = /* @__PURE__ */ new Map();
 	registeredHandler = () => {};
 	goneHandler = () => {};
+	/** Source of {@link RegisteredChild.incarnation}; one bump per accepted connection. */
+	nextIncarnation = 1;
 	eventHandler = null;
 	logHandler = null;
 	readinessHandler = null;
@@ -5106,14 +5108,20 @@ var LocalChildRegistry = class {
 	listChildren() {
 		return [...this.children.values()].map((e) => ({
 			childId: e.childId,
-			caps: e.caps
+			caps: e.caps,
+			incarnation: e.incarnation
 		}));
 	}
 	/** Register the (single) child-registered handler. Only one handler is active at a time. */
 	onChildRegistered(handler) {
 		this.registeredHandler = handler;
 	}
-	/** Register the (single) child-gone handler. Only one handler is active at a time. */
+	/**
+	* Register the (single) child-gone handler. Only one handler is active at a
+	* time. The handler receives the {@link RegisteredChild.incarnation} of the
+	* connection that closed — carry it into whatever teardown it triggers, so a
+	* dead generation cannot tear down its successor's work.
+	*/
 	onChildGone(handler) {
 		this.goneHandler = handler;
 	}
@@ -5198,6 +5206,7 @@ var LocalChildRegistry = class {
 	}
 	onConnection(channel) {
 		let childId = null;
+		const incarnation = this.nextIncarnation++;
 		channel.onEvent((body) => {
 			const msg = body;
 			if (msg.kind === "event") {
@@ -5226,16 +5235,24 @@ var LocalChildRegistry = class {
 				if (childId !== null && childId !== msg.childId) throw new Error(`child attempted to change identity from "${childId}" to "${msg.childId}"`);
 				childId = msg.childId;
 				const eventPatterns = msg.eventPatterns ?? null;
+				const superseded = this.children.get(msg.childId);
+				if (superseded !== void 0 && superseded.channel !== channel) this.logger?.info("local child superseded by a new connection", {
+					childId: msg.childId,
+					supersededIncarnation: superseded.incarnation,
+					incarnation
+				});
 				this.children.set(msg.childId, {
 					childId: msg.childId,
 					channel,
 					caps: msg.caps,
-					eventPatterns
+					eventPatterns,
+					incarnation
 				});
 				this.logPatternSet(msg.childId, eventPatterns);
 				this.registeredHandler({
 					childId: msg.childId,
-					caps: msg.caps
+					caps: msg.caps,
+					incarnation
 				});
 				return { ok: true };
 			}
@@ -5270,11 +5287,21 @@ var LocalChildRegistry = class {
 			throw new Error(`unknown child request kind: ${msg.kind}`);
 		});
 		channel.onClose(() => {
-			if (childId !== null && this.children.delete(childId)) {
-				this.childEventStats.delete(childId);
-				this.loggedPatternSet.delete(childId);
-				this.goneHandler(childId);
+			if (childId === null) return;
+			const entry = this.children.get(childId);
+			if (entry === void 0) return;
+			if (entry.channel !== channel) {
+				this.logger?.info("ignoring close of a superseded local child connection", {
+					childId,
+					incarnation,
+					liveIncarnation: entry.incarnation
+				});
+				return;
 			}
+			this.children.delete(childId);
+			this.childEventStats.delete(childId);
+			this.loggedPatternSet.delete(childId);
+			this.goneHandler(childId, incarnation);
 		});
 	}
 };

package/dist/{manifest-python-deps-GejnH--L.js → manifest-python-deps-MA_BZGBz.js}

@@ -4836,6 +4836,8 @@ var LocalChildRegistry = class {
 	children = /* @__PURE__ */ new Map();
 	registeredHandler = () => {};
 	goneHandler = () => {};
+	/** Source of {@link RegisteredChild.incarnation}; one bump per accepted connection. */
+	nextIncarnation = 1;
 	eventHandler = null;
 	logHandler = null;
 	readinessHandler = null;
@@ -5110,14 +5112,20 @@ var LocalChildRegistry = class {
 	listChildren() {
 		return [...this.children.values()].map((e) => ({
 			childId: e.childId,
-			caps: e.caps
+			caps: e.caps,
+			incarnation: e.incarnation
 		}));
 	}
 	/** Register the (single) child-registered handler. Only one handler is active at a time. */
 	onChildRegistered(handler) {
 		this.registeredHandler = handler;
 	}
-	/** Register the (single) child-gone handler. Only one handler is active at a time. */
+	/**
+	* Register the (single) child-gone handler. Only one handler is active at a
+	* time. The handler receives the {@link RegisteredChild.incarnation} of the
+	* connection that closed — carry it into whatever teardown it triggers, so a
+	* dead generation cannot tear down its successor's work.
+	*/
 	onChildGone(handler) {
 		this.goneHandler = handler;
 	}
@@ -5202,6 +5210,7 @@ var LocalChildRegistry = class {
 	}
 	onConnection(channel) {
 		let childId = null;
+		const incarnation = this.nextIncarnation++;
 		channel.onEvent((body) => {
 			const msg = body;
 			if (msg.kind === "event") {
@@ -5230,16 +5239,24 @@ var LocalChildRegistry = class {
 				if (childId !== null && childId !== msg.childId) throw new Error(`child attempted to change identity from "${childId}" to "${msg.childId}"`);
 				childId = msg.childId;
 				const eventPatterns = msg.eventPatterns ?? null;
+				const superseded = this.children.get(msg.childId);
+				if (superseded !== void 0 && superseded.channel !== channel) this.logger?.info("local child superseded by a new connection", {
+					childId: msg.childId,
+					supersededIncarnation: superseded.incarnation,
+					incarnation
+				});
 				this.children.set(msg.childId, {
 					childId: msg.childId,
 					channel,
 					caps: msg.caps,
-					eventPatterns
+					eventPatterns,
+					incarnation
 				});
 				this.logPatternSet(msg.childId, eventPatterns);
 				this.registeredHandler({
 					childId: msg.childId,
-					caps: msg.caps
+					caps: msg.caps,
+					incarnation
 				});
 				return { ok: true };
 			}
@@ -5274,11 +5291,21 @@ var LocalChildRegistry = class {
 			throw new Error(`unknown child request kind: ${msg.kind}`);
 		});
 		channel.onClose(() => {
-			if (childId !== null && this.children.delete(childId)) {
-				this.childEventStats.delete(childId);
-				this.loggedPatternSet.delete(childId);
-				this.goneHandler(childId);
+			if (childId === null) return;
+			const entry = this.children.get(childId);
+			if (entry === void 0) return;
+			if (entry.channel !== channel) {
+				this.logger?.info("ignoring close of a superseded local child connection", {
+					childId,
+					incarnation,
+					liveIncarnation: entry.incarnation
+				});
+				return;
 			}
+			this.children.delete(childId);
+			this.childEventStats.delete(childId);
+			this.loggedPatternSet.delete(childId);
+			this.goneHandler(childId, incarnation);
 		});
 	}
 };

package/package.json

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