@harperfast/harper 5.2.0-beta.4 → 5.2.1

package/components/componentLoader.ts

@@ -29,6 +29,8 @@ import * as scheduler from '../resources/scheduler/scheduler.ts';
 import { restartWorkers, getWorkerIndex } from '../server/threads/manageThreads.js';
 import { resetRestartNeeded, subscribeToRestartRequests } from './requestRestart.ts';
 import { trackScopeClose } from './scopeShutdown.ts';
+import { deployLifecycle } from './deployLifecycle.ts';
+import { toScopeMount, nestScopeMount, type ScopeMount } from './scopeMount.ts';
 import { scopedImport } from '../security/jsLoader.ts';
 import { server } from '../server/Server.ts';
 import { Resources } from '../resources/Resources.ts';
@@ -63,6 +65,51 @@ let resources;
  * @param loadedPluginModules
  * @param loadedResources
  */
+/**
+ * The application mount an operator declared for `appName` in the root config.
+ *
+ * Applications in the components root are loaded by directory scan, not from a root-config
+ * entry, so this is what makes a root-config entry authoritative for where an app is served:
+ *
+ * ```yaml
+ * my-app:
+ *   host: api.example.com
+ *   urlPath: /v1
+ * ```
+ *
+ * Works whether or not the entry also carries `package` — a payload-deployed app is mounted the
+ * same way as an installed one. A built-in plugin's config block is never an application mount;
+ * those keys (`http`, `mqtt`, …) configure the plugin itself.
+ */
+function rootConfigMount(appName: string): ScopeMount | undefined {
+	if (Object.hasOwn(TRUSTED_RESOURCE_PLUGINS, appName)) return undefined;
+	return toScopeMount(getConfigObj()?.[appName]);
+}
+
+/**
+ * Resolves the mount for `appName`, or reports the failure and returns `undefined` if the
+ * configured `host`/`urlPath` is invalid. The caller must skip loading the application in that
+ * case rather than loading it anyway: an invalid mount is a request to CONSTRAIN where the app is
+ * served, so loading it unconstrained would silently drop the isolation the operator configured
+ * (review finding) — worse than not loading it at all. Isolated per-app so one bad mount doesn't
+ * take down every other application's load.
+ */
+function tryRootConfigMount(appName: string): { ok: true; mount: ScopeMount | undefined } | { ok: false } {
+	try {
+		return { ok: true, mount: rootConfigMount(appName) };
+	} catch (error) {
+		(error as Error).message = `Not loading '${appName}': invalid routing configured: ${(error as Error).message}`;
+		errorReporter?.(error);
+		(getWorkerIndex() === 0 ? console : harperLogger).error(errorForLog(error as Error));
+		componentLifecycle.failed(
+			appName,
+			error as Error,
+			`Component '${appName}' failed to load due to invalid routing configuration`
+		);
+		return { ok: false };
+	}
+}
+
 export async function loadComponentDirectories(loadedPluginModules?: Map<any, any>, loadedResources?: Resources) {
 	if (loadedResources) resources = loadedResources;
 	if (loadedPluginModules) loadedComponents = loadedPluginModules;
@@ -81,21 +128,32 @@ export async function loadComponentDirectories(loadedPluginModules?: Map<any, an
 			if (appEntry.name.startsWith('.')) continue;
 			const appName = appEntry.name;
 			const appFolder = join(CF_ROUTES_DIR, appName);
+			const mountResult = tryRootConfigMount(appName);
+			if (!mountResult.ok) continue;
 			cfsLoaded.push(
-				loadComponent(appFolder, resources, HDB_ROOT_DIR_NAME, { isRoot: false, autoReload: false, appName })
+				loadComponent(appFolder, resources, HDB_ROOT_DIR_NAME, {
+					isRoot: false,
+					autoReload: false,
+					appName,
+					mount: mountResult.mount,
+				})
 			);
 		}
 	}
 	const hdbAppFolder = process.env.RUN_HDB_APP;
 	if (hdbAppFolder) {
 		if (getWorkerIndex() === 0) harperLogger.info?.('Loading application from ' + hdbAppFolder);
-		cfsLoaded.push(
-			loadComponent(hdbAppFolder, resources, hdbAppFolder, {
-				isRoot: false,
-				autoReload: Boolean(process.env.DEV_MODE),
-				appName: hdbAppFolder,
-			})
-		);
+		const mountResult = tryRootConfigMount(basename(hdbAppFolder));
+		if (mountResult.ok) {
+			cfsLoaded.push(
+				loadComponent(hdbAppFolder, resources, hdbAppFolder, {
+					isRoot: false,
+					autoReload: Boolean(process.env.DEV_MODE),
+					appName: hdbAppFolder,
+					mount: mountResult.mount,
+				})
+			);
+		}
 	}
 	return Promise.all(cfsLoaded).then(() => {
 		watchesSetup = true;
@@ -113,6 +171,16 @@ export const TRUSTED_RESOURCE_PLUGINS: any = {
 		return require('../server/fastifyRoutes');
 	},
 	login,
+	// String entry: the loader `await import()`s these lazily when the component is actually
+	// processed, so the gateway's module graph is not pulled into componentLoader's own
+	// evaluation. `#src/*` is used rather than a relative path because it resolves under both
+	// conditions (source under --conditions=typestrip, dist otherwise); a relative extensionless
+	// require would only resolve against dist.
+	//
+	// The component is only *processed* when a `modelsGateway` key exists in the config, since
+	// the root loop skips absent keys (`if (!componentConfig) continue`). `defaultConfig.yaml`
+	// ships no such key, so an instance that never opts in pays nothing for this entry.
+	modelsGateway: '#src/resources/models/v1/index',
 	static: staticFiles,
 	customFunctions: {},
 	http: httpComponent,
@@ -255,6 +323,7 @@ function symlinkHarperModule(componentDirectory: string) {
  */
 function sequentiallyHandleApplication(scope: Scope, plugin: PluginModule) {
 	return scope.ready.then(async () => {
+		await scope.waitForDeployCompletion();
 		// Timeout priority is user config, plugin default, finally 30 seconds
 		const timeout = scope.options.get(['timeout']) || plugin.defaultTimeout || 30_000; // default 30 second timeout
 		if (typeof timeout !== 'number') {
@@ -276,35 +345,76 @@ function sequentiallyHandleApplication(scope: Scope, plugin: PluginModule) {
 				}, timeout + 5_000); // extra time for lock acquisition
 			});
 		}
-		let loadTimeout: NodeJS.Timeout;
 		try {
 			// note that handleApplication can throw sync or async errors, need to run finally block for both
-			await Promise.race([
+			await withDeployAwareTimeout(
 				Promise.resolve(plugin.handleApplication(scope)).then(async () => {
 					// Wait for any initial entry handler loads to complete
 					// This ensures all async operations (like secureImport) finish before the component is marked as loaded
 					await scope.waitForInitialLoads();
 				}),
-				new Promise(
-					(_, reject) =>
-						(loadTimeout = setTimeout(
-							() =>
-								reject(
-									new Error(
-										`handleApplication timed out after ${timeout}ms for ${scope.pluginName} on behalf of ${scope.appName}`
-									)
-								),
-							timeout
-						))
-				),
-			]);
+				scope,
+				timeout
+			);
 		} finally {
 			Status.primaryStore.unlock(scope.pluginName);
-			clearTimeout(loadTimeout);
 		}
 	});
 }
 
+function withDeployAwareTimeout<T>(operation: Promise<T>, scope: Scope, timeout: number): Promise<T> {
+	return new Promise((resolve, reject) => {
+		const absoluteTimeout = timeout + 6 * 60 * 60 * 1000;
+		let remaining = timeout;
+		let activeSince = 0;
+		let timer: NodeJS.Timeout | undefined;
+		let absoluteTimer: NodeJS.Timeout;
+		const cleanup = () => {
+			if (timer) clearTimeout(timer);
+			clearTimeout(absoluteTimer);
+			deployLifecycle.off('deploy:start', handleDeployStart);
+			deployLifecycle.off('deploy:end', handleDeployEnd);
+		};
+		const rejectTimeout = (limit = timeout) => {
+			cleanup();
+			reject(
+				new Error(`handleApplication timed out after ${limit}ms for ${scope.pluginName} on behalf of ${scope.appName}`)
+			);
+		};
+		absoluteTimer = setTimeout(() => rejectTimeout(absoluteTimeout), absoluteTimeout);
+		absoluteTimer.unref?.();
+		const arm = () => {
+			if (deployLifecycle.isDeployInFlight(scope.appName)) return;
+			if (remaining <= 0) return rejectTimeout();
+			activeSince = Date.now();
+			timer = setTimeout(rejectTimeout, remaining);
+		};
+		function handleDeployStart(componentName: string) {
+			if (componentName !== scope.appName || !timer) return;
+			remaining -= Date.now() - activeSince;
+			clearTimeout(timer);
+			timer = undefined;
+		}
+		function handleDeployEnd(componentName: string) {
+			if (componentName === scope.appName) arm();
+		}
+
+		deployLifecycle.on('deploy:start', handleDeployStart);
+		deployLifecycle.on('deploy:end', handleDeployEnd);
+		operation.then(
+			(value) => {
+				cleanup();
+				resolve(value);
+			},
+			(error) => {
+				cleanup();
+				reject(error);
+			}
+		);
+		arm();
+	});
+}
+
 export interface LoadComponentOptions {
 	isRoot?: boolean;
 	applicationScope?: ApplicationScope;
@@ -316,6 +426,10 @@ export interface LoadComponentOptions {
 	// (e.g. the deploy pre-flight validation) so their deploy-lifecycle listeners don't accumulate
 	// across deploys (#1462).
 	collectScopes?: Set<Scope>;
+	// Routing the operator declared for this application in the root config (`host`/`urlPath` on
+	// the application's entry). Applied to every plugin scope this load creates, and inherited by
+	// components the application itself declares, so the whole subtree moves together.
+	mount?: ScopeMount;
 }
 
 /**
@@ -342,7 +456,9 @@ export async function loadComponent(
 		isRoot,
 		autoReload,
 		appName,
+		mount,
 	} = options;
+	applicationScope.runtimeRoot ??= resolvedFolder;
 	applicationScope.allowedPath ??= realpathSync(componentDirectory);
 	if (providedLoadedComponents) loadedComponents = providedLoadedComponents;
 	try {
@@ -485,6 +601,13 @@ export async function loadComponent(
 								autoReload: false,
 								appName: appName || componentName,
 								collectScopes: options.collectScopes,
+								// `host`/`urlPath` on this entry route the component being loaded. For an
+								// application (no plugin module of its own) that entry is the only place an
+								// operator can say where the app is served — its own config.yaml declares the
+								// plugins, not the deployment. A nested component's own mount nests inside
+								// the parent's rather than replacing it, and the parent keeps hostname
+								// authority, so a child can't escape the host it is served on.
+								mount: nestScopeMount(mount, toScopeMount(componentConfig)),
 							});
 							componentFunctionality[componentName] = true;
 						}
@@ -554,7 +677,10 @@ export async function loadComponent(
 						// authoritative root-ness: only root-load scopes watch THE root config and
 						// get the runtime env-config overlay (#1618) — an app component that happens
 						// to ship a root-named config file does not
-						isRoot
+						isRoot,
+						// A root-declared plugin reads its own `host`/`urlPath` straight from this
+						// config, so only an inherited application mount applies here.
+						mount
 					);
 
 					if (options.collectScopes) {
@@ -597,6 +723,32 @@ export async function loadComponent(
 					);
 				}
 
+				// `start`/`startOnMainThread` hand the plugin the raw, unmounted `server` directly —
+				// unlike the new Plugin API's `handleApplication(scope)`, which receives the mount-aware
+				// scope — so routes registered there would silently escape a configured host/urlPath
+				// mount and stay reachable unconstrained (review finding). Same isolation gap
+				// fastifyRoutes.ts already closes for its own legacy fallback (host-only there, since
+				// urlPath composes into its route prefix; here neither composes, so both are rejected).
+				// Refuse rather than imply an isolation the hook can't honor; contained to this
+				// component by the loader's per-component try/catch.
+				if (
+					mount &&
+					(typeof extensionModule.start === 'function' || typeof extensionModule.startOnMainThread === 'function')
+				) {
+					const error = new Error(
+						`Component '${componentName}' is mounted (${[
+							mount.host && `host '${mount.host}'`,
+							mount.urlPath && `urlPath '${mount.urlPath}'`,
+						]
+							.filter(Boolean)
+							.join(
+								', '
+							)}), but its deprecated 'start'/'startOnMainThread' extension API receives the bare, unmounted server — routes registered there would stay reachable unconstrained. Upgrade to the new Plugin API (handleApplication(scope)) or drop the mount.`
+					);
+					componentLifecycle.failed(componentStatusName, error, `Component '${componentStatusName}' failed to load`);
+					throw error;
+				}
+
 				if (isMainThread) {
 					// `startOnMainThread` is one-time main-thread init: run it at most once per component
 					// for the life of the process (first load / first deploy). On a reload of an

package/components/deployLifecycle.ts

@@ -9,25 +9,39 @@
 //
 // This module solves that by broadcasting a structured "deploy:start" /
 // "deploy:end" signal to every Harper thread. Each thread's deploy emitter
-// fires locally so Scopes (and any plugin subscribers) can react: Scopes close
-// their EntryHandlers on start, recreate them on end. The result is that
+// fires locally so Scopes (and any plugin subscribers) can react: Scopes pause
+// their EntryHandlers on start and resume them on end. The result is that
 // during a deploy, no watcher fires events for the deployed component, and
-// after the deploy the recreated watcher emits one fresh add per current file
-// — collapsed by the existing restart debounce into a single restart.
+// after the deploy the watcher compares the new tree with its retained snapshot
+// and emits the same logical add/change/unlink events consumers saw before #1806.
 //
-// State sharing across threads is intentionally narrow: the local Set of
-// in-flight component names is rebuilt from the broadcast stream. Plugins that
-// need to gate their own work on deploy progress import `deployLifecycle` and
-// listen to the events directly.
+// State sharing across threads is intentionally narrow: local deployment-owner
+// records are rebuilt from the broadcast stream and reclaimed when their owner
+// thread exits. Plugins that need to gate their own work on deploy progress
+// import `deployLifecycle` and listen to the events directly.
 
 import { EventEmitter } from 'node:events';
-import { isMainThread } from 'node:worker_threads';
-import { broadcast, broadcastWithAcknowledgement, onMessageByType } from '../server/threads/manageThreads.js';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { isMainThread, threadId } from 'node:worker_threads';
+import {
+	broadcast,
+	broadcastWithAcknowledgement,
+	isThreadRunning,
+	onMessageByType,
+	onThreadExit,
+} from '../server/threads/manageThreads.js';
+import harperLogger from '../utility/logging/harper_logger.ts';
 
 const DEPLOY_LIFECYCLE_MSG = 'harper:deploy:lifecycle';
 
 export type DeployPhase = 'start' | 'end';
-export type DeployLifecycleEvent = { name: string; phase: DeployPhase };
+export type DeployLifecycleEvent = {
+	name: string;
+	phase: DeployPhase;
+	deploymentId?: string;
+	ownerThreadId?: number;
+};
 
 type DeployLifecycleEventsMap = {
 	'deploy:start': [componentName: string];
@@ -35,44 +49,109 @@ type DeployLifecycleEventsMap = {
 };
 
 class DeployLifecycle extends EventEmitter<DeployLifecycleEventsMap> {
-	// Ref-counts in-flight deploys per component. Concurrent deploys of the
-	// same name (rare, but possible if an operator queues two before the first
-	// resolves) overlap: 0→1 fires deploy:start, 1→0 fires deploy:end. Any
-	// intermediate increment/decrement is silent so watchers aren't toggled
-	// out from under an active deploy by a peer ending early.
-	#inFlight = new Map<string, number>();
+	#deployments = new Map<string, { name: string; ownerThreadId: number }>();
+	#byComponent = new Map<string, Set<string>>();
+	#deadOwners = new Set<number>();
+	#legacyDeployments = new Map<string, string[]>();
+	#legacySequence = 0;
 
 	isDeployInFlight(componentName: string): boolean {
-		return (this.#inFlight.get(componentName) ?? 0) > 0;
+		return (this.#byComponent.get(componentName)?.size ?? 0) > 0;
 	}
 
 	// Process a deploy lifecycle event in-process. Called both from the
 	// broadcast receiver (for events originating on another thread) and from
 	// the broadcaster (so the originating thread also reacts locally).
 	_handle(event: DeployLifecycleEvent): void {
-		const current = this.#inFlight.get(event.name) ?? 0;
+		const ownerThreadId = event.ownerThreadId ?? threadId;
+		let deploymentId = event.deploymentId;
 		if (event.phase === 'start') {
-			this.#inFlight.set(event.name, current + 1);
-			if (current === 0) this.emit('deploy:start', event.name);
-		} else {
-			const next = Math.max(0, current - 1);
-			if (next === 0) {
-				this.#inFlight.delete(event.name);
-				if (current > 0) this.emit('deploy:end', event.name);
-			} else {
-				this.#inFlight.set(event.name, next);
+			if (this.#deadOwners.has(ownerThreadId)) return;
+			if (!deploymentId) {
+				deploymentId = `legacy:${threadId}:${++this.#legacySequence}`;
+				const legacy = this.#legacyDeployments.get(event.name) ?? [];
+				legacy.push(deploymentId);
+				this.#legacyDeployments.set(event.name, legacy);
+			}
+			if (this.#deployments.has(deploymentId)) return;
+			const active = this.#byComponent.get(event.name) ?? new Set<string>();
+			this.#deployments.set(deploymentId, { name: event.name, ownerThreadId });
+			this.#byComponent.set(event.name, active);
+			active.add(deploymentId);
+			if (active.size === 1) this.#emitSafely('deploy:start', event.name);
+			return;
+		}
+		if (!deploymentId) deploymentId = this.#legacyDeployments.get(event.name)?.pop();
+		if (deploymentId) this.#removeDeployment(deploymentId);
+	}
+
+	_reclaimOwner(ownerThreadId: number): void {
+		this.#deadOwners.add(ownerThreadId);
+		for (const [deploymentId, deployment] of this.#deployments) {
+			if (deployment.ownerThreadId === ownerThreadId) this.#removeDeployment(deploymentId);
+		}
+	}
+
+	async _reclaimOwnerAfterTermination(
+		ownerThreadId: number,
+		waitForTermination: (ownerThreadId: number) => Promise<void> = waitForOwnerTermination
+	): Promise<void> {
+		if (ownerThreadId === 0 || ownerThreadId === threadId) return;
+		this.#deadOwners.add(ownerThreadId);
+		await waitForTermination(ownerThreadId);
+		this._reclaimOwner(ownerThreadId);
+	}
+
+	#removeDeployment(deploymentId: string): void {
+		const deployment = this.#deployments.get(deploymentId);
+		if (!deployment) return;
+		this.#deployments.delete(deploymentId);
+		const active = this.#byComponent.get(deployment.name);
+		if (!active) return;
+		active.delete(deploymentId);
+		if (active.size === 0) {
+			this.#byComponent.delete(deployment.name);
+			this.#emitSafely('deploy:end', deployment.name);
+		}
+	}
+
+	#emitSafely(event: 'deploy:start' | 'deploy:end', componentName: string): void {
+		for (const listener of this.rawListeners(event)) {
+			try {
+				listener.call(this, componentName);
+			} catch (error) {
+				harperLogger.error(`Listener for ${event} threw for ${componentName}:`, error);
 			}
 		}
 	}
 
 	// Test-only: clear in-flight state without firing events.
 	_clearForTests(): void {
-		this.#inFlight.clear();
+		this.#deployments.clear();
+		this.#byComponent.clear();
+		this.#deadOwners.clear();
+		this.#legacyDeployments.clear();
+		this.#legacySequence = 0;
 	}
 }
 
 export const deployLifecycle = new DeployLifecycle();
 
+async function waitForOwnerTermination(ownerThreadId: number): Promise<void> {
+	let timeoutReported = false;
+	for (;;) {
+		try {
+			if (!(await isThreadRunning(ownerThreadId))) return;
+		} catch (error) {
+			if (!timeoutReported) {
+				timeoutReported = true;
+				harperLogger.warn(`Retrying liveness check for exited thread ${ownerThreadId}:`, error);
+			}
+		}
+		await delay(25, undefined, { ref: false });
+	}
+}
+
 let receiverInstalled = false;
 function ensureReceiver() {
 	if (receiverInstalled) return;
@@ -88,6 +167,11 @@ function ensureReceiver() {
 // suppress only the main thread's watchers and the worker watchers would keep
 // firing restart storms (harper#488).
 ensureReceiver();
+onThreadExit((deadThreadId: number) => {
+	void deployLifecycle
+		._reclaimOwnerAfterTermination(deadThreadId)
+		.catch((error) => harperLogger.error(`Could not reclaim deployments from thread ${deadThreadId}:`, error));
+});
 
 /**
  * Announce the start of a deploy for `componentName`. Awaits acknowledgement
@@ -98,9 +182,10 @@ ensureReceiver();
  * component compose correctly (each call must be paired with exactly one
  * broadcastDeployEnd).
  */
-export async function broadcastDeployStart(componentName: string): Promise<void> {
+export async function broadcastDeployStart(componentName: string): Promise<string> {
 	ensureReceiver();
-	const event: DeployLifecycleEvent = { name: componentName, phase: 'start' };
+	const deploymentId = randomUUID();
+	const event: DeployLifecycleEvent = { name: componentName, phase: 'start', deploymentId, ownerThreadId: threadId };
 	deployLifecycle._handle(event); // local thread first
 	let timer: ReturnType<typeof setTimeout> | undefined;
 	try {
@@ -125,6 +210,7 @@ export async function broadcastDeployStart(componentName: string): Promise<void>
 	} finally {
 		if (timer) clearTimeout(timer);
 	}
+	return deploymentId;
 }
 
 /**
@@ -135,9 +221,9 @@ export async function broadcastDeployStart(componentName: string): Promise<void>
  * Must be called exactly once per matching broadcastDeployStart, even if the
  * deploy errored — typically from a `finally` block.
  */
-export function broadcastDeployEnd(componentName: string): void {
+export function broadcastDeployEnd(componentName: string, deploymentId: string): void {
 	ensureReceiver();
-	const event: DeployLifecycleEvent = { name: componentName, phase: 'end' };
+	const event: DeployLifecycleEvent = { name: componentName, phase: 'end', deploymentId, ownerThreadId: threadId };
 	deployLifecycle._handle(event);
 	try {
 		void broadcast({ type: DEPLOY_LIFECYCLE_MSG, event }, false);

package/components/mcp/toolRegistry.ts

@@ -362,6 +362,16 @@ export function isSuperUser(user: AuthedUser | undefined): boolean {
 	return user?.role?.permission?.super_user === true;
 }
 
+/**
+ * True if the request carries an authenticated principal. Anonymous MCP sessions are a supported
+ * deployment (the public-docs case, #1609) — the adapter hands them through as `{ username: '' }`
+ * rather than rejecting them — so a listing filter that means "any real user" has to test for this
+ * explicitly. `user?.role` is not a proxy: an authenticated user may legitimately carry no role.
+ */
+export function isAuthenticated(user: AuthedUser | undefined): boolean {
+	return typeof user?.username === 'string' && user.username.length > 0;
+}
+
 /**
  * Class-level verb introspection. Mirrors `resources/openApi.ts:149-153` so
  * a class is considered to "have" a verb only if its prototype overrides the

package/components/mcp/tools/application.ts

@@ -27,6 +27,7 @@ import harperLogger from '../../../utility/logging/harper_logger.ts';
 import {
 	addTool,
 	clearProfileTools,
+	isAuthenticated,
 	snapshotProfileTools,
 	type AuthedUser,
 	type ToolCallContext,
@@ -708,11 +709,17 @@ function makeVisibleTo(
 	return function visibleTo(user: AuthedUser): boolean {
 		// Super-user sees everything.
 		if (user?.role?.permission?.super_user === true) return true;
-		// Non-table Resources have no static permission gate — runtime allow*
-		// predicates enforce. Conservative default: don't list them for
-		// non-super users; they can still call via tools/call if they know
-		// the tool name (pass-through is documented behavior).
-		if (!databaseName || !tableName) return false;
+		// A Resource with no backing table has no static permission gate to consult, so listing is
+		// open to any authenticated caller and the Resource's own `allow*` predicates enforce at call
+		// time — hiding these while still accepting `tools/call` on them bought no security, only
+		// undiscoverable tools (#1940).
+		//
+		// Anonymous sessions stay excluded. They are a supported deployment (#1609) and reach here as
+		// `{ username: '' }`, so this must be tested explicitly. Custom `mcpTools` DO list to them, but
+		// that is an author opt-in — declaring `static mcpTools` is a deliberate act of publishing.
+		// Verb tools are generated for every exported Resource with no author action, so publishing an
+		// app's field names and docstrings to unauthenticated callers by default is not equivalent.
+		if (!databaseName || !tableName) return isAuthenticated(user);
 		const perm = getUserTablePermissions(user, databaseName, tableName);
 		if (!perm) return false;
 		if (mode === 'read') return perm.read === true || perm.describe === true;

package/components/mcp/tools/operations.ts

@@ -176,6 +176,9 @@ const DESTRUCTIVE_OPERATIONS: ReadonlySet<string> = new Set([
 	'restart_service',
 	'set_configuration',
 	'remove_node',
+	'restore_backup',
+	'delete_backup',
+	'purge_backups',
 	'delete_deployment_payload',
 ]);
 
@@ -300,6 +303,12 @@ export function makeOperationToolHandler(operationName: string) {
 			operation: operationName,
 			hdb_user: context.user,
 		};
+		// Authorization bypass is internal dispatch state, never client-supplied tool
+		// arguments — mirrors handlePostRequest's stripping in serverHandlers.js. Without
+		// this, a caller-supplied `bypass_auth`/`bypassAuth` argument would reach handlers
+		// (e.g. createTokens) that trust it directly from the body.
+		delete body.bypass_auth;
+		delete body.bypassAuth;
 		if (STREAMING_OPERATIONS.has(operationName)) {
 			// Reject before the handler runs at all — see STREAMING_OPERATIONS' comment for why
 			// destroying an already-returned stream isn't sufficient cleanup for these producers.

package/components/mcp/tools/schemas/operationDescriptions.ts

@@ -60,6 +60,9 @@ export const OPERATION_DESCRIPTIONS: Record<string, string> = {
 	// list_deployments: components/deploymentOperations.ts:50 — Deployment history with filtering and pagination.
 	list_deployments:
 		'Lists deployments from system.hdb_deployment with optional filtering by project, status, and date range, plus pagination.',
+	// list_backups: dataLayer/rocksdbBackup.ts (listBackups) — Managed RocksDB backup metadata for a database.
+	list_backups:
+		'Lists the managed RocksDB directory backups for a database (id, timestamp, size, file count). Requires super_user; RocksDB databases only.',
 
 	// ─── DEFAULT_ALLOW: search_* ──────────────────────────────────────────
 	// search_by_conditions: dataLayer/search.ts:6 — Multi-condition search with comparators.

package/components/mcp/tools/schemas/operations.ts

@@ -101,6 +101,15 @@ export const OPERATION_INPUT_SCHEMAS: Record<string, object> = {
 		properties: {},
 		description: 'Lists deployed component versions in this Harper instance.',
 	},
+	list_backups: {
+		type: 'object',
+		properties: {
+			database: {
+				type: 'string',
+				description: 'Database name whose managed RocksDB backups to list. Defaults to `data`.',
+			},
+		},
+	},
 
 	// ─── search_* ─────────────────────────────────────────────────────────
 	search_by_hash: {

package/components/operations.js

@@ -410,6 +410,7 @@ async function deployComponent(req) {
 			};
 		}
 		if (req.urlPath !== undefined) applicationConfig.urlPath = req.urlPath;
+		if (req.host !== undefined) applicationConfig.host = req.host;
 		// Persist credential references (never tokens) so every cold install of this component —
 		// reboot, new peer, rollback — re-resolves the credential from the store.
 		if (credentialReferences.length) applicationConfig.credentials = credentialReferences;
@@ -645,12 +646,10 @@ async function deployComponent(req) {
 			// deploy checks its own local isNewComponent, since directory state (and therefore
 			// whether the component was already active) can differ per node.
 			//
-			// An existing, already-active component being redeployed does NOT force a restart
-			// here: some updates (e.g. static files only) may not need one at all, and when one
-			// genuinely is needed, that component's already-running file watcher (Scope/
-			// EntryHandler, see deployLifecycle.ts) independently detects the post-deploy file
-			// changes and requests the restart itself.
-			if (application.isNewComponent) {
+			// An existing component's watched files are handled by Scope/EntryHandler. Package
+			// metadata is deliberately outside most plugin globs, so compare it across the atomic
+			// swap as well: a dependency or module-entry change also invalidates loaded code.
+			if (application.isNewComponent || application.packageMetadataChanged) {
 				const { requestRestart } = require('./requestRestart.ts');
 				requestRestart();
 			}