harper 5.1.20 → 5.2.0-alpha.5

package/agent/operations.ts

@@ -1,10 +1,13 @@
 /**
  * Operations API surface for the built-in agent (#626).
  *
- * Six handlers, all super_user-only — the auth check is inline because none
- * of these ops are registered in `utility/operation_authorization.ts`'s
- * `requiredPermissions` map. Without the inline gate, a non-SU request would
- * fall through the standard flow and be allowed.
+ * Six handlers, super_user by default. Authorization is declared via
+ * `requiresSuperUser: true` on each OperationDefinition, so `registerOperation`
+ * registers them with the central `verifyPerms` system and they participate in
+ * the role `operations` allowlist — an operator can grant a scoped, non-super_user
+ * "delegation" role access to these ops (e.g. `operations: ['agent']`) without
+ * granting full super_user. verifyPerms runs before the handler for every
+ * ops-API request, so no inline gate is needed here.
  */
 
 import type { OperationDefinition } from '../server/serverHelpers/serverUtilities.ts';
@@ -25,38 +28,37 @@ export function buildOperations(deps: OperationDeps): OperationDefinition[] {
 		{
 			name: OPERATIONS_ENUM.AGENT_PROMPT,
 			execute: async (op) => agentPrompt(op, deps),
+			requiresSuperUser: true,
 		},
 		{
 			name: OPERATIONS_ENUM.GET_AGENT_SESSION,
 			execute: async (op) => getAgentSession(op),
+			requiresSuperUser: true,
 		},
 		{
 			name: OPERATIONS_ENUM.LIST_AGENT_SESSIONS,
 			execute: async (op) => listAgentSessions(op),
+			requiresSuperUser: true,
 		},
 		{
 			name: OPERATIONS_ENUM.CANCEL_AGENT_RUN,
 			execute: async (op) => cancelAgentRun(op, deps),
+			requiresSuperUser: true,
 		},
 		{
 			name: OPERATIONS_ENUM.APPROVE_AGENT_ACTION,
 			execute: async (op) => approveAgentAction(op, deps),
+			requiresSuperUser: true,
 		},
 		{
 			name: OPERATIONS_ENUM.SET_AGENT_CONFIG,
 			execute: async (op) => setAgentConfig(op, deps),
+			requiresSuperUser: true,
 		},
 	];
 }
 
-function requireSuperUser(op: any): void {
-	if (!op?.hdb_user?.role?.permission?.super_user) {
-		throw new ClientError('Agent operations require super_user', 403);
-	}
-}
-
 async function agentPrompt(op: any, deps: OperationDeps) {
-	requireSuperUser(op);
 	const config = deps.getConfig();
 	if (!config.enabled) {
 		throw new ClientError('Agent component is disabled (agent.enabled=false)', 409);
@@ -90,7 +92,6 @@ async function agentPrompt(op: any, deps: OperationDeps) {
 }
 
 async function getAgentSession(op: any) {
-	requireSuperUser(op);
 	const sessionId = String(op?.session_id ?? '');
 	if (!sessionId) throw new ClientError('session_id is required', 400);
 	const session = await getSession(sessionId);
@@ -99,13 +100,11 @@ async function getAgentSession(op: any) {
 }
 
 async function listAgentSessions(op: any) {
-	requireSuperUser(op);
 	const limit = Number.isFinite(op?.limit) ? Number(op.limit) : undefined;
 	return { sessions: await listSessions({ limit }) };
 }
 
 async function cancelAgentRun(op: any, deps: OperationDeps) {
-	requireSuperUser(op);
 	const sessionId = String(op?.session_id ?? '');
 	if (!sessionId) throw new ClientError('session_id is required', 400);
 	const session = await getSession(sessionId);
@@ -120,7 +119,6 @@ async function cancelAgentRun(op: any, deps: OperationDeps) {
 }
 
 async function approveAgentAction(op: any, deps: OperationDeps) {
-	requireSuperUser(op);
 	const sessionId = String(op?.session_id ?? '');
 	const approvalId = String(op?.approval_id ?? '');
 	if (!sessionId || !approvalId) {
@@ -135,7 +133,6 @@ async function approveAgentAction(op: any, deps: OperationDeps) {
 }
 
 async function setAgentConfig(op: any, deps: OperationDeps) {
-	requireSuperUser(op);
 	const patch: Partial<AgentConfig> = {};
 	for (const key of ['enabled', 'provider', 'model', 'maxTurns', 'maxCostUsd', 'autoApprove', 'allowDestructive']) {
 		if (op?.[key] !== undefined) (patch as any)[key] = op[key];

package/components/Application.ts

@@ -20,6 +20,7 @@ import {
 	writeFile,
 } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
 import { randomUUID } from 'node:crypto';
 import { createReadStream, existsSync, readdirSync } from 'node:fs';
 import { Readable } from 'node:stream';
@@ -37,6 +38,10 @@ interface ApplicationConfig {
 		timeout?: number;
 		allowInstallScripts?: boolean;
 	};
+	// Private-registry auth in reference form only — each entry names an hdb_secret row, never a
+	// token. Recorded by deploy_component so every (cold) install — reboot, new peer, rollback —
+	// re-resolves the credential from the store rather than needing it re-supplied.
+	registryAuth?: { registry: string; secret: string; scope?: string }[];
 	// an application config can have other arbitrary properties
 	[key: string]: unknown;
 }
@@ -73,6 +78,22 @@ export class InvalidInstallTimeoutError extends TypeError {
 	}
 }
 
+export class InvalidRegistryAuthPropertyError extends TypeError {
+	constructor(applicationName: string, registryAuth: unknown) {
+		super(
+			`Invalid 'registryAuth' property for application ${applicationName}: expected array, got ${typeof registryAuth}`
+		);
+	}
+}
+
+export class InvalidRegistryAuthEntryError extends TypeError {
+	constructor(applicationName: string) {
+		super(
+			`Invalid 'registryAuth' entry for application ${applicationName}: expected { registry, secret, scope? } reference`
+		);
+	}
+}
+
 export function assertApplicationConfig(
 	applicationName: string,
 	applicationConfig: Record<'package', unknown> & Record<string, unknown>
@@ -110,6 +131,24 @@ export function assertApplicationConfig(
 			);
 		}
 	}
+	if ('registryAuth' in applicationConfig && applicationConfig.registryAuth !== undefined) {
+		const entries = applicationConfig.registryAuth;
+		if (!Array.isArray(entries)) {
+			throw new InvalidRegistryAuthPropertyError(applicationName, entries);
+		}
+		for (const entry of entries) {
+			// Config carries references only — a literal `token` here would mean a plaintext credential
+			// was persisted to disk, which the deploy path is designed to prevent.
+			if (
+				typeof entry !== 'object' ||
+				entry === null ||
+				typeof (entry as any).registry !== 'string' ||
+				typeof (entry as any).secret !== 'string'
+			) {
+				throw new InvalidRegistryAuthEntryError(applicationName);
+			}
+		}
+	}
 }
 
 /**
@@ -210,7 +249,10 @@ export async function extractApplication(application: Application) {
 				application.name,
 				'npm',
 				['pack', '--json', application.packageIdentifier],
-				parentDirPath
+				parentDirPath,
+				undefined,
+				undefined,
+				application.npmUserconfigPath
 			);
 			if (code !== 0) {
 				if (isSSHAuthFailure(stderr)) {
@@ -354,7 +396,8 @@ export async function installApplication(application: Application) {
 			args,
 			application.dirPath,
 			application.install?.timeout,
-			customOnLine
+			customOnLine,
+			application.npmUserconfigPath
 		);
 		// if it succeeds, return
 		if (code === 0) {
@@ -414,7 +457,8 @@ export async function installApplication(application: Application) {
 			application.install?.allowInstallScripts ? ['install'] : ['install', '--ignore-scripts'], // All of `npm`, `yarn`, and `pnpm` support the `install` command. If we need to configure options here we may have to use some other defaults though
 			application.dirPath,
 			application.install?.timeout,
-			pmOnLine
+			pmOnLine,
+			application.npmUserconfigPath
 		);
 
 		// if it succeeds, return
@@ -470,7 +514,8 @@ export async function installApplication(application: Application) {
 		npmInstallArgs,
 		application.dirPath,
 		application.install?.timeout,
-		npmOnLine
+		npmOnLine,
+		application.npmUserconfigPath
 	);
 
 	// if it succeeds, return
@@ -506,6 +551,7 @@ interface ApplicationOptions {
 	packageIdentifier?: string;
 	install?: { command?: string; timeout?: number; allowInstallScripts?: boolean };
 	onInstallLine?: OnInstallLine;
+	registryAuth?: RegistryAuthEntry[];
 }
 
 export class Application {
@@ -517,19 +563,75 @@ export class Application {
 	dirPath: string;
 	logger: Logger;
 	packageManagerPrefix: string; // can be used to configure a package manager prefix, specifically "sfw".
-
-	constructor({ name, payload, packageIdentifier, install, onInstallLine }: ApplicationOptions) {
+	// Transient registry auth provided by a deploy. The token is held only in memory and a
+	// per-deploy `.npmrc`; it is never persisted to config, hdb_deployment, or replicated.
+	registryAuth?: RegistryAuthEntry[];
+	// Path to the per-deploy `.npmrc`, set by writeTransientNpmrc() during prepareApplication and
+	// passed to the spawn calls; undefined when no registry auth was provided.
+	npmUserconfigPath?: string;
+	#npmrcTempDir?: string;
+
+	constructor({ name, payload, packageIdentifier, install, onInstallLine, registryAuth }: ApplicationOptions) {
 		this.name = name;
 		this.payload = payload;
 		this.packageIdentifier = packageIdentifier && derivePackageIdentifier(packageIdentifier);
 		this.install = install;
 		this.onInstallLine = onInstallLine;
+		this.registryAuth = registryAuth;
 		const componentsRoot = getConfigPath(CONFIG_PARAMS.COMPONENTSROOT);
 		if (!componentsRoot) throw new Error('componentsRoot is not configured');
 		this.dirPath = join(componentsRoot, name);
 		this.logger = logger.loggerWithTag(name);
 		this.packageManagerPrefix = getConfigValue(CONFIG_PARAMS.APPLICATIONS_PACKAGEMANAGERPREFIX);
 	}
+
+	// Write the transient `.npmrc` into a fresh 0700 temp dir (file mode 0600) and record its path
+	// so the deploy's npm spawns authenticate against the private registry. No-op without registry auth.
+	//
+	// Because `nonInteractiveSpawn` points npm at this single file (replacing any inherited
+	// npm_config_userconfig), prepend the contents of an already-configured userconfig — e.g. a
+	// fabric-injected file carrying cluster registries, a proxy, or a cafile — so those settings
+	// survive. The transient auth is appended last so it wins on conflict (npm honors the last
+	// value for a given key).
+	async writeTransientNpmrc(): Promise<void> {
+		if (!this.registryAuth?.length) return;
+		// Defensive: if called more than once, remove the prior temp dir first so it isn't leaked.
+		if (this.#npmrcTempDir) await this.cleanupTransientNpmrc();
+		this.#npmrcTempDir = await mkdtemp(join(tmpdir(), 'harper-npmrc-'));
+		const npmrcPath = join(this.#npmrcTempDir, '.npmrc');
+		let content = '';
+		const inheritedUserconfig = process.env.npm_config_userconfig ?? process.env.NPM_CONFIG_USERCONFIG;
+		if (inheritedUserconfig) {
+			try {
+				const inherited = await readFile(inheritedUserconfig, 'utf8');
+				content = inherited.endsWith('\n') ? inherited : inherited + '\n';
+			} catch (error: any) {
+				// Missing inherited file is fine (npm would have created/ignored it); surface anything else.
+				if (error?.code !== 'ENOENT') throw error;
+			}
+		}
+		content += buildNpmrcContent(this.registryAuth);
+		await writeFile(npmrcPath, content, { mode: 0o600 });
+		this.npmUserconfigPath = npmrcPath;
+	}
+
+	// Remove the transient `.npmrc` (and its temp dir) once the deploy's npm work is done.
+	async cleanupTransientNpmrc(): Promise<void> {
+		if (!this.#npmrcTempDir) return;
+		try {
+			await rm(this.#npmrcTempDir, { recursive: true, force: true });
+		} catch (error) {
+			// Called from prepareApplication's finally; a throw here (e.g. a Windows file lock) would
+			// mask the original deploy error and skip broadcastDeployEnd. Log and always clear state.
+			this.logger.warn(`Failed to remove transient .npmrc dir ${this.#npmrcTempDir}:`, error);
+		} finally {
+			this.#npmrcTempDir = undefined;
+			this.npmUserconfigPath = undefined;
+			// Drop the in-memory token array too, so it can't surface in a later heap dump or error
+			// serialization of this Application instance.
+			this.registryAuth = undefined;
+		}
+	}
 }
 
 /**
@@ -569,9 +671,13 @@ export function derivePackageIdentifier(packageIdentifier: string) {
 export async function prepareApplication(application: Application) {
 	await broadcastDeployStart(application.name);
 	try {
+		// Materialize the per-deploy `.npmrc` before extraction so both `npm pack` (extract) and
+		// `npm install` authenticate against the private registry; always remove it afterward.
+		await application.writeTransientNpmrc();
 		await extractApplication(application);
 		await installApplication(application);
 	} finally {
+		await application.cleanupTransientNpmrc();
 		broadcastDeployEnd(application.name);
 	}
 }
@@ -631,10 +737,29 @@ export async function installApplications() {
 			// This will throw if the config is invalid
 			assertApplicationConfig(name, applicationConfig);
 
+			// Resolve any private-registry auth references from the store so a cold install (fresh
+			// node, wiped components dir, new peer that never installed) can authenticate without the
+			// token being re-supplied. Best-effort: if custody isn't available yet or a referenced
+			// secret is missing, log and install without it (a truly private package then fails in
+			// npm with its own error) rather than blocking boot.
+			let resolvedRegistryAuth: RegistryAuthEntry[] | undefined;
+			if (applicationConfig.registryAuth?.length) {
+				try {
+					const { resolveRegistryAuth } = await import('./secretOperations.ts');
+					resolvedRegistryAuth = (await resolveRegistryAuth(applicationConfig.registryAuth, name)) as
+						RegistryAuthEntry[] | undefined;
+				} catch (error) {
+					logger.warn?.(
+						`Could not resolve registryAuth for application ${name} at install time: ${(error as Error).message}`
+					);
+				}
+			}
+
 			const application = new Application({
 				name,
 				packageIdentifier: applicationConfig.package,
 				install: applicationConfig.install,
+				registryAuth: resolvedRegistryAuth,
 			});
 
 			// Lock check: only install if not already installed with matching configuration
@@ -675,6 +800,49 @@ function getGitSSHCommand() {
 	}
 }
 
+export interface RegistryAuthEntry {
+	registry: string;
+	token: string;
+	scope?: string;
+}
+
+// Normalize a registry to a full URL with a scheme and trailing slash, e.g.
+// `npm.pkg.github.com` or `//npm.pkg.github.com` → `https://npm.pkg.github.com/`.
+function normalizeRegistryUrl(registry: string): string {
+	let url = registry.trim();
+	if (!/^https?:\/\//i.test(url)) {
+		url = url.startsWith('//') ? `https:${url}` : `https://${url}`;
+	}
+	if (!url.endsWith('/')) url += '/';
+	return url;
+}
+
+// Build the contents of a transient `.npmrc` from registry auth entries: an auth-token line keyed
+// by npm's registry auth key (scheme stripped, leading `//`, trailing `/`) plus a registry-routing
+// line. A scope routes only that `@scope` to the registry (`@scope:registry=…`); without a scope
+// the entry sets npm's default `registry=…` so an unscoped package spec (e.g. `npm:my-private-app`)
+// or its transitive deps actually resolve against this registry rather than the public default.
+// A scope-less entry therefore requires its registry to serve/proxy whatever npm needs to install;
+// with multiple scope-less entries npm's last-value-wins applies to the default `registry`.
+export function buildNpmrcContent(registryAuth: RegistryAuthEntry[]): string {
+	const lines: string[] = [];
+	for (const { registry, token, scope } of registryAuth) {
+		// Enforce the no-newline invariant at the injection point so it holds for every source. The
+		// ops validator already rejects CR/LF in a literal `token`, but a token resolved from an
+		// hdb_secret row bypasses that guard; without this a `\n` in a secret value would inject
+		// arbitrary .npmrc lines (admin-only per the threat model, but the literal path already
+		// defends this class).
+		if (/[\r\n]/.test(token)) {
+			throw new Error(`registry auth token for '${registry}' contains an illegal newline character`);
+		}
+		const registryUrl = normalizeRegistryUrl(registry);
+		const authKey = registryUrl.replace(/^https?:/i, '');
+		lines.push(`${authKey}:_authToken=${token}`);
+		lines.push(scope ? `${scope}:registry=${registryUrl}` : `registry=${registryUrl}`);
+	}
+	return lines.join('\n') + '\n';
+}
+
 /**
  * Execute a command (using `spawn`) with stdin ignored.
  *
@@ -734,7 +902,8 @@ export function nonInteractiveSpawn(
 	args: string[],
 	cwd: string,
 	timeoutMs: number = 60 * 60 * 1000,
-	onLine?: (stream: 'stdout' | 'stderr', line: string) => void
+	onLine?: (stream: 'stdout' | 'stderr', line: string) => void,
+	npmUserconfigPath?: string
 ): Promise<{ stdout: string; stderr: string; code: number }> {
 	return new Promise((resolve, reject) => {
 		logger
@@ -748,6 +917,18 @@ export function nonInteractiveSpawn(
 			env.GIT_SSH_COMMAND = gitSSHCommand;
 		}
 
+		// A deploy carrying transient registry auth points npm at a per-deploy `.npmrc` so
+		// `npm pack`/`install` can authenticate against a private registry without the token
+		// ever touching disk durably, the package reference, config, or hdb_deployment.
+		if (npmUserconfigPath) {
+			// On case-insensitive platforms (Windows) an inherited NPM_CONFIG_USERCONFIG would
+			// shadow the lowercase key we set, so drop any existing case variant first.
+			for (const key of Object.keys(env)) {
+				if (key.toLowerCase() === 'npm_config_userconfig') delete env[key];
+			}
+			env.npm_config_userconfig = npmUserconfigPath;
+		}
+
 		if (process.platform === 'win32' && command === 'npm') {
 			command = 'npm.cmd';
 		}

package/components/ApplicationScope.ts

@@ -16,6 +16,8 @@ export class MissingDefaultFilesOptionError extends Error {
  * This class is used to represent the application scope for the VM context used for loading modules within an application
  */
 export class ApplicationScope {
+	/** Component identity (application directory name) — what secret grants are matched against. */
+	name: string;
 	logger: any;
 	resources: Resources;
 	server: Server;
@@ -25,6 +27,7 @@ export class ApplicationScope {
 	config: any;
 	moduleCache: any; // used by the loader to retain a cache of modules, type is an internal detail of the loader
 	constructor(name: string, resources: Resources, server: Server, isInternal = false) {
+		this.name = name;
 		this.logger = forComponent(name, !isInternal);
 
 		this.resources = resources;

package/components/Scope.ts

@@ -12,6 +12,7 @@ import { FilesOption } from './deriveGlobOptions.ts';
 import { requestRestart } from './requestRestart.ts';
 import { resolveBaseURLPath } from './resolveBaseURLPath.ts';
 import { ApplicationScope } from './ApplicationScope.ts';
+import { getSecretsForComponent } from './componentSecrets.ts';
 import { deployLifecycle } from './deployLifecycle.ts';
 
 export class MissingDefaultFilesOptionError extends Error {
@@ -146,6 +147,17 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 		return this.#logger;
 	}
 
+	/**
+	 * The application's secrets view (#1550): hdb_secret rows granted to this application plus its
+	 * declared global-tier env names. Frozen, enumerable, values decrypted at component load.
+	 * Keyed by the ApplicationScope's name (the application directory name — the identity grants
+	 * and env declarations use, and the same binding `import { secrets } from 'harper'` resolves);
+	 * `#appName` can differ on paths like RUN_HDB_APP, where it is the full directory path.
+	 */
+	get secrets(): Readonly<Record<string, string>> {
+		return getSecretsForComponent(this.applicationScope?.name ?? this.#appName);
+	}
+
 	get appName(): string {
 		return this.#appName;
 	}

package/components/anthropic/index.ts

@@ -257,7 +257,10 @@ export class AnthropicBackend implements ModelBackend {
 			signal,
 		});
 		if (!res.ok) {
-			throw new AnthropicBackendError(`Anthropic ${path} returned HTTP ${res.status}${await readErrorSuffix(res)}`);
+			throw new AnthropicBackendError(
+				`Anthropic ${path} returned HTTP ${res.status}${await readErrorSuffix(res)}`,
+				res.status
+			);
 		}
 		return res;
 	}
@@ -283,9 +286,13 @@ export function registerAnthropicBackend(args: {
 }
 
 export class AnthropicBackendError extends ServerError {
-	constructor(message: string) {
+	/** HTTP status returned by the upstream provider, when the failure came from an HTTP response.
+	 * Distinct from ServerError's statusCode, which is Harper's own response status (#1593). */
+	declare upstreamStatus?: number;
+	constructor(message: string, upstreamStatus?: number) {
 		super(message);
 		this.name = 'AnthropicBackendError';
+		if (upstreamStatus !== undefined) this.upstreamStatus = upstreamStatus;
 	}
 }
 

package/components/bedrock/index.ts

@@ -256,6 +256,11 @@ export class BedrockBackend implements ModelBackend {
 	 * Send a command with caller-supplied AbortSignal + optional per-call
 	 * timeout composed via `AbortSignal.any`. The SDK accepts `abortSignal`
 	 * in the request options bag.
+	 *
+	 * SDK `ServiceException`s are re-thrown as `BedrockBackendError` carrying the
+	 * upstream HTTP status (`$metadata.httpStatusCode`) so the sanitized `@embed`
+	 * error is diagnosable, matching the openai/anthropic/ollama backends (#1593).
+	 * Aborts/timeouts are caller-driven, not upstream failures — propagated untouched.
 	 */
 	async #sendWithAbort(
 		client: { send: (cmd: object, options?: { abortSignal?: AbortSignal }) => Promise<unknown> },
@@ -263,7 +268,21 @@ export class BedrockBackend implements ModelBackend {
 		callerSignal?: AbortSignal
 	): Promise<unknown> {
 		const abortSignal = composeSignal(callerSignal, this.#requestTimeoutMs);
-		return client.send(command, abortSignal ? { abortSignal } : undefined);
+		try {
+			return await client.send(command, abortSignal ? { abortSignal } : undefined);
+		} catch (err) {
+			if ((err as any)?.name === 'AbortError' || abortSignal?.aborted) throw err;
+			const status = (err as any)?.$metadata?.httpStatusCode;
+			const sdkName = (err as any)?.name;
+			const wrapped = new BedrockBackendError(
+				`Bedrock request failed${sdkName ? ` (${sdkName})` : ''}`,
+				typeof status === 'number' ? status : undefined
+			);
+			// Keep the raw SDK error for the unsanitized server log; only class name +
+			// upstreamStatus surface to callers.
+			(wrapped as any).cause = err;
+			throw wrapped;
+		}
 	}
 }
 
@@ -284,9 +303,13 @@ export function registerBedrockBackend(args: {
 }
 
 export class BedrockBackendError extends ServerError {
-	constructor(message: string) {
+	/** HTTP status returned by the upstream provider, when the failure came from an HTTP response.
+	 * Distinct from ServerError's statusCode, which is Harper's own response status (#1593). */
+	declare upstreamStatus?: number;
+	constructor(message: string, upstreamStatus?: number) {
 		super(message);
 		this.name = 'BedrockBackendError';
+		if (upstreamStatus !== undefined) this.upstreamStatus = upstreamStatus;
 	}
 }
 

package/components/componentLoader.ts

@@ -23,7 +23,7 @@ import * as login from '../resources/login.ts';
 import * as REST from '../server/REST.ts';
 import * as staticFiles from '../server/static.ts';
 import * as loadEnv from '../resources/loadEnv.ts';
-import harperLogger from '../utility/logging/harper_logger.ts';
+import harperLogger, { errorForLog } from '../utility/logging/harper_logger.ts';
 import * as dataLoader from '../resources/dataLoader.ts';
 import { restartWorkers, getWorkerIndex } from '../server/threads/manageThreads.js';
 import { resetRestartNeeded, subscribeToRestartRequests } from './requestRestart.ts';
@@ -46,6 +46,7 @@ import * as mcpComponent from './mcp/index.ts';
 import { Status } from '../server/status/index.ts';
 import { lifecycle as componentLifecycle } from './status/index.ts';
 import { DEFAULT_CONFIG } from './DEFAULT_CONFIG.ts';
+import { materializeGlobalSecrets, processComponentEnv } from './componentSecrets.ts';
 import { PluginModule } from './PluginModule.ts';
 import { getEnvBuiltInComponents } from './Application.ts';
 import { pathToFileURL } from 'node:url';
@@ -61,9 +62,14 @@ let resources;
  * @param loadedPluginModules
  * @param loadedResources
  */
-export function loadComponentDirectories(loadedPluginModules?: Map<any, any>, loadedResources?: Resources) {
+export async function loadComponentDirectories(loadedPluginModules?: Map<any, any>, loadedResources?: Resources) {
 	if (loadedResources) resources = loadedResources;
 	if (loadedPluginModules) loadedComponents = loadedPluginModules;
+	// Materialize hdb_secret global-tier rows into process.env and snapshot the scoped tier before
+	// any application loads (root components — including the Pro custody registration — have
+	// already loaded by this point). Re-runs on each reload cycle, which is how changed/late-custody
+	// secrets heal. Never throws.
+	await materializeGlobalSecrets();
 	const cfsLoaded: Promise<any>[] = [];
 	if (existsSync(CF_ROUTES_DIR)) {
 		const cfFolders = readdirSync(CF_ROUTES_DIR, { withFileTypes: true });
@@ -303,6 +309,11 @@ export interface LoadComponentOptions {
 	autoReload?: boolean;
 	providedLoadedComponents?: Map<any, any>;
 	appName?: string;
+	// When provided, every Scope created during this load is added to this set instead of being
+	// auto-closed on worker shutdown. The caller then owns closing them. Used by transient loads
+	// (e.g. the deploy pre-flight validation) so their deploy-lifecycle listeners don't accumulate
+	// across deploys (#1462).
+	collectScopes?: Set<Scope>;
 }
 
 /**
@@ -366,6 +377,34 @@ export async function loadComponent(
 		// per-component iteration below; built-in entries register synchronously.
 		if (isRoot) await bootstrapModels(config);
 
+		// The `env:` block declares the component's environment expectations (string literal →
+		// process.env; object → declaration satisfied from the hdb_secret store / process.env).
+		// Processed before any of the component's plugins load, so literals and the load-gate apply
+		// to everything below. A failed gate contains to this component — nothing of this
+		// component's is registered (its URL space is simply absent) and the instance keeps running.
+		if (config.env !== undefined) {
+			if (isRoot) {
+				harperLogger.warn(
+					`The 'env' config block is not supported in the root config; declare env expectations in each component's config`
+				);
+			} else {
+				const componentStatusName = basename(componentDirectory);
+				try {
+					// Refresh the store snapshot so out-of-cycle loads (e.g. deploy validation in a
+					// long-lived worker, after a set_secret/grant_secret since boot) gate against
+					// current data. Cheap (one small system-table scan per env-declaring component).
+					await materializeGlobalSecrets();
+					processComponentEnv(componentStatusName, config.env);
+				} catch (error) {
+					error.message = `Could not load component '${componentStatusName}' due to: ${error.message}`;
+					errorReporter?.(error);
+					(getWorkerIndex() === 0 ? console : harperLogger).error(error);
+					componentLifecycle.failed(componentStatusName, error, `Could not load component '${componentStatusName}'`);
+					return undefined;
+				}
+			}
+		}
+
 		if (!isRoot) {
 			try {
 				await symlinkHarperModule(componentDirectory);
@@ -383,6 +422,7 @@ export async function loadComponent(
 		const componentFunctionality = {};
 		// iterate through the app handlers so they can each do their own loading process
 		for (const componentName in config) {
+			if (componentName === 'env') continue; // handled above — not a plugin
 			// For root components, use just the component name
 			// For application components, use applicationName.componentName format (directoryName.componentName)
 			const componentStatusName = isRoot ? componentName : `${basename(componentDirectory)}.${componentName}`;
@@ -442,6 +482,7 @@ export async function loadComponent(
 								applicationScope: subApplicationScope,
 								autoReload: false,
 								appName: appName || componentName,
+								collectScopes: options.collectScopes,
 							});
 							componentFunctionality[componentName] = true;
 						}
@@ -510,9 +551,17 @@ export async function loadComponent(
 						origin
 					);
 
-					// Track the close so the worker's shutdown path waits for it (and thus for any async
-					// native-runtime disposal, e.g. @harperfast/vite's dev server) before calling realExit.
-					onMessageByType(ITC_EVENT_TYPES.SHUTDOWN, () => trackScopeClose(scope.close()));
+					if (options.collectScopes) {
+						// A transient/validation load owns these scopes and closes them itself once the
+						// load is validated (see operations.js deploy pre-flight). Skip the worker-shutdown
+						// auto-close so their deploy-lifecycle listeners — and this SHUTDOWN handler — don't
+						// accumulate across deploys (#1462).
+						options.collectScopes.add(scope);
+					} else {
+						// Track the close so the worker's shutdown path waits for it (and thus for any async
+						// native-runtime disposal, e.g. @harperfast/vite's dev server) before calling realExit.
+						onMessageByType(ITC_EVENT_TYPES.SHUTDOWN, () => trackScopeClose(scope.close()));
+					}
 
 					await sequentiallyHandleApplication(scope, extensionModule);
 
@@ -607,7 +656,7 @@ export async function loadComponent(
 					error.message
 				}`;
 				errorReporter?.(error);
-				(getWorkerIndex() === 0 ? console : harperLogger).error(error);
+				(getWorkerIndex() === 0 ? console : harperLogger).error(errorForLog(error));
 				resources.set(componentConfig.path || '/', new ErrorResource(error), null, true);
 				componentLifecycle.failed(componentStatusName, error, `Could not load component '${componentStatusName}'`);
 			}
@@ -683,7 +732,7 @@ export async function loadComponent(
 				);
 		}
 	} catch (error) {
-		console.error(`Could not load application directory ${componentDirectory}`, error);
+		console.error(`Could not load application directory ${componentDirectory}`, errorForLog(error));
 		error.message = `Could not load application due to ${error.message}`;
 		errorReporter?.(error);
 		resources.set('', new ErrorResource(error));