envpkt 0.11.1 → 0.11.3

package/dist/cli.js

@@ -3,7 +3,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync,
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { Cond, Either, Left, List, Option, Right, Try } from "functype";
+import { $, Cond, Do, Either, Left, List, Map as Map$1, Option, Right, Set as Set$1, Try } from "functype";
 import { TypeCompiler } from "@sinclair/typebox/compiler";
 import { Env, Fs, Path, Platform } from "functype-os";
 import { TomlDate, parse, stringify } from "smol-toml";
@@ -27,20 +27,26 @@ const classifySecret = (key, meta, fnoxKeys, staleWarningDays, requireExpiration
 	const issues = [];
 	const created = Option(meta.created).flatMap(parseDate);
 	const expires = Option(meta.expires).flatMap(parseDate);
+	const lastRotated = Option(meta.last_rotated_at).flatMap(parseDate);
 	const rotationUrl = Option(meta.rotation_url);
 	const purpose = Option(meta.purpose);
 	const service = Option(meta.service);
 	const daysRemaining = expires.map((exp) => daysBetween(today, exp));
-	const daysSinceCreated = created.map((c) => daysBetween(c, today));
+	const staleFromRotation = lastRotated.isSome();
+	const daysSinceRotation = (staleFromRotation ? lastRotated : created).map((d) => daysBetween(d, today));
 	const isExpired = daysRemaining.fold(() => false, (d) => d < 0);
 	const isExpiringSoon = daysRemaining.fold(() => false, (d) => d >= 0 && d <= WARN_BEFORE_DAYS);
-	const isStale = daysSinceCreated.fold(() => false, (d) => d > staleWarningDays);
+	const isStale = daysSinceRotation.fold(() => false, (d) => d > staleWarningDays);
 	const hasSealed = !!meta.encrypted_value;
 	const isMissing = fnoxKeys.size > 0 && !fnoxKeys.has(key) && !hasSealed;
 	const isMissingMetadata = requireExpiration && expires.isNone() || requireService && service.isNone();
 	if (isExpired) issues.push("Secret has expired");
 	if (isExpiringSoon) issues.push(`Expires in ${daysRemaining.fold(() => "?", (d) => String(d))} days`);
-	if (isStale) issues.push("Secret is stale (no rotation detected)");
+	if (isStale) {
+		const since = daysSinceRotation.fold(() => "?", (d) => String(d));
+		const label = staleFromRotation ? "last rotated" : "created";
+		issues.push(`Secret is stale (${label} ${since} days ago)`);
+	}
 	if (isMissing) issues.push("Key not found in fnox");
 	if (isMissingMetadata) {
 		if (requireExpiration && expires.isNone()) issues.push("Missing required expiration date");
@@ -55,6 +61,7 @@ const classifySecret = (key, meta, fnoxKeys, staleWarningDays, requireExpiration
 		purpose,
 		created: Option(meta.created),
 		expires: Option(meta.expires),
+		last_rotated_at: Option(meta.last_rotated_at),
 		issues: List(issues),
 		alias_of: Option(void 0)
 	};
@@ -70,9 +77,10 @@ const classifyAlias = (key, meta, targetHealth, targetRef) => ({
 	status: targetHealth.status,
 	days_remaining: targetHealth.days_remaining,
 	rotation_url: targetHealth.rotation_url,
-	purpose: meta.purpose !== void 0 ? Option(meta.purpose) : targetHealth.purpose,
+	purpose: Option(meta.purpose).fold(() => targetHealth.purpose, (v) => Option(v)),
 	created: targetHealth.created,
 	expires: targetHealth.expires,
+	last_rotated_at: targetHealth.last_rotated_at,
 	issues: List([]),
 	alias_of: Option(targetRef)
 });
@@ -86,17 +94,18 @@ const computeAudit = (config, fnoxKeys, today, aliasTable) => {
 	const secretEntries = config.secret ?? {};
 	const nonAliasEntries = Object.entries(secretEntries).filter(([, meta]) => meta.from_key === void 0);
 	const aliasEntries = Object.entries(secretEntries).filter(([, meta]) => meta.from_key !== void 0);
-	const nonAliasMetaKeys = new Set(nonAliasEntries.map(([k]) => k));
+	const nonAliasMetaKeys = Set$1(nonAliasEntries.map(([k]) => k));
 	const nonAliasHealth = nonAliasEntries.map(([key, meta]) => classifySecret(key, meta, keys, staleWarningDays, requireExpiration, requireService, now));
-	const healthByKey = new Map(nonAliasHealth.map((h) => [h.key, h]));
+	const healthByKey = Map$1(nonAliasHealth.map((h) => [h.key, h]));
 	const parseTargetKey = (from_key) => {
-		return /^secret\.(.+)$/.exec(from_key)?.[1];
+		return Option(from_key.match(/^secret\.(.+)$/)?.[1]);
 	};
 	const aliasHealth = aliasEntries.map(([key, meta]) => {
-		const targetKey = (aliasTable?.entries.get(`secret.${key}`))?.targetKey ?? (meta.from_key !== void 0 ? parseTargetKey(meta.from_key) : void 0);
-		const targetHealth = targetKey !== void 0 ? healthByKey.get(targetKey) : void 0;
-		const targetRef = meta.from_key ?? (targetKey !== void 0 ? `secret.${targetKey}` : "");
-		if (!targetHealth) return {
+		const tableEntry = aliasTable?.entries.get(`secret.${key}`);
+		const targetKey = Option(tableEntry?.targetKey).fold(() => Option(meta.from_key).flatMap(parseTargetKey), (k) => Option(k));
+		const targetHealth = targetKey.flatMap((k) => healthByKey.get(k));
+		const targetRef = Option(meta.from_key).fold(() => targetKey.map((k) => `secret.${k}`), (v) => Option(v)).orElse("");
+		return targetHealth.fold(() => ({
 			key,
 			service: Option(meta.service),
 			status: "missing",
@@ -105,13 +114,13 @@ const computeAudit = (config, fnoxKeys, today, aliasTable) => {
 			purpose: Option(meta.purpose),
 			created: Option(meta.created),
 			expires: Option(meta.expires),
+			last_rotated_at: Option(meta.last_rotated_at),
 			issues: List(["Alias target not resolvable"]),
 			alias_of: Option(targetRef)
-		};
-		return classifyAlias(key, meta, targetHealth, targetRef);
+		}), (health) => classifyAlias(key, meta, health, targetRef));
 	});
 	const secrets = List([...nonAliasHealth, ...aliasHealth]);
-	const orphaned = keys.size > 0 ? [...nonAliasMetaKeys].filter((k) => !keys.has(k)).length : 0;
+	const orphaned = keys.size > 0 ? nonAliasMetaKeys.toArray().filter((k) => !keys.has(k)).length : 0;
 	const total = secrets.size;
 	const expired = secrets.count((s) => s.status === "expired");
 	const missing = secrets.count((s) => s.status === "missing");
@@ -137,12 +146,14 @@ const computeAudit = (config, fnoxKeys, today, aliasTable) => {
 };
 const computeEnvAudit = (config, env = process.env) => {
 	const envEntries = config.env ?? {};
+	const resolveEffectiveDefault = (entry) => {
+		return Do(function* () {
+			return yield* $(Option((yield* $(Option(envEntries[yield* $(Option((yield* $(Option(entry.from_key))).match(/^env\.(.+)$/)?.[1]))]))).value));
+		}).orElse(entry.value ?? "");
+	};
 	const entries = Object.entries(envEntries).map(([key, entry]) => {
 		const currentValue = env[key];
-		const effectiveDefault = entry.from_key !== void 0 ? (() => {
-			const targetKey = /^env\.(.+)$/.exec(entry.from_key)?.[1];
-			return (targetKey !== void 0 ? envEntries[targetKey] : void 0)?.value ?? "";
-		})() : entry.value ?? "";
+		const effectiveDefault = resolveEffectiveDefault(entry);
 		return {
 			key,
 			defaultValue: effectiveDefault,
@@ -203,6 +214,10 @@ const SecretMetaSchema = Type.Object({
 		format: "date",
 		description: "Date the secret was provisioned (YYYY-MM-DD)"
 	})),
+	last_rotated_at: Type.Optional(Type.String({
+		format: "date",
+		description: "Date the secret value was most recently rotated (YYYY-MM-DD). Used by audit for staleness."
+	})),
 	rotates: Type.Optional(Type.String({ description: "Rotation schedule (e.g. '90d', 'quarterly')" })),
 	rate_limit: Type.Optional(Type.String({ description: "Rate limit or quota info (e.g. '1000/min')" })),
 	model_hint: Type.Optional(Type.String({ description: "Suggested model or tier for this credential" })),
@@ -427,18 +442,19 @@ const loadCatalog = (catalogPath) => loadConfig(catalogPath).fold((err) => {
 /** Resolve secrets by merging catalog meta with agent overrides (shallow merge) */
 const resolveSecrets = (agentMeta, catalogMeta, agentSecrets, catalogPath) => {
 	return agentSecrets.reduce((acc, key) => acc.flatMap((resolved) => {
-		if (!(key in catalogMeta)) return Left({
+		const catalogEntry = catalogMeta[key];
+		if (catalogEntry === void 0) return Left({
 			_tag: "SecretNotInCatalog",
 			key,
 			catalogPath
 		});
-		const catalogEntry = catalogMeta[key];
+		const merged = Option(agentMeta[key]).fold(() => catalogEntry, (override) => ({
+			...catalogEntry,
+			...override
+		}));
 		return Right({
 			...resolved,
-			[key]: key in agentMeta ? {
-				...catalogEntry,
-				...agentMeta[key]
-			} : catalogEntry
+			[key]: merged
 		});
 	}), Right({}));
 };
@@ -898,12 +914,12 @@ const validateOneSecret = (key, meta, secretEntries) => {
 		kind: "secret",
 		field: "encrypted_value"
 	});
-	return parseRef(ref).fold(() => Left({
+	return parseRef(ref).toEither({
 		_tag: "AliasInvalidSyntax",
 		key,
 		kind: "secret",
 		value: ref
-	}), (parsed) => {
+	}).flatMap((parsed) => {
 		if (parsed.kind !== "secret") return Left({
 			_tag: "AliasCrossType",
 			key,
@@ -914,23 +930,23 @@ const validateOneSecret = (key, meta, secretEntries) => {
 			_tag: "AliasSelfReference",
 			key: `secret.${key}`
 		});
-		return Option(secretEntries[parsed.key]).fold(() => Left({
+		return Option(secretEntries[parsed.key]).toEither({
 			_tag: "AliasTargetMissing",
 			key: `secret.${key}`,
 			target: ref
-		}), (target) => {
+		}).flatMap((target) => {
 			if (target.from_key !== void 0) return Left({
 				_tag: "AliasChained",
 				key: `secret.${key}`,
 				target: ref
 			});
-			return Right(Option({
+			return Right({
 				kind: "secret",
 				targetKind: "secret",
 				targetKey: parsed.key
-			}));
+			});
 		});
-	});
+	}).map((entry) => Option(entry));
 };
 const validateOneEnv = (key, meta, envEntries) => {
 	if (meta.from_key === void 0) return Right(Option(void 0));
@@ -941,12 +957,12 @@ const validateOneEnv = (key, meta, envEntries) => {
 		kind: "env",
 		field: "value"
 	});
-	return parseRef(ref).fold(() => Left({
+	return parseRef(ref).toEither({
 		_tag: "AliasInvalidSyntax",
 		key,
 		kind: "env",
 		value: ref
-	}), (parsed) => {
+	}).flatMap((parsed) => {
 		if (parsed.kind !== "env") return Left({
 			_tag: "AliasCrossType",
 			key,
@@ -957,57 +973,43 @@ const validateOneEnv = (key, meta, envEntries) => {
 			_tag: "AliasSelfReference",
 			key: `env.${key}`
 		});
-		return Option(envEntries[parsed.key]).fold(() => Left({
+		return Option(envEntries[parsed.key]).toEither({
 			_tag: "AliasTargetMissing",
 			key: `env.${key}`,
 			target: ref
-		}), (target) => {
+		}).flatMap((target) => {
 			if (target.from_key !== void 0) return Left({
 				_tag: "AliasChained",
 				key: `env.${key}`,
 				target: ref
 			});
-			return Right(Option({
+			return Right({
 				kind: "env",
 				targetKind: "env",
 				targetKey: parsed.key
-			}));
+			});
 		});
-	});
+	}).map((entry) => Option(entry));
 };
-/**
-* Validate all `from_key` references in a resolved config. Produces an
-* AliasTable mapping each alias to its target, or an AliasError describing
-* the first failure.
-*
-* Rules:
-* - Ref must be "secret.<KEY>" or "env.<KEY>"
-* - Target must exist in the same resolved config
-* - Target must be the same type (secret→secret, env→env only)
-* - Target must not itself be a from_key entry (single hop only)
-* - Self-reference is rejected
-* - An alias entry cannot also carry a value field (encrypted_value for
-*   secrets, value for env)
-*/
+/** Fail-fast reduction: accumulates validated entries, short-circuits on first AliasError */
+const collectValidated = (items, validate, prefix) => items.reduce((acc, [key, meta]) => acc.flatMap((entries) => validate(key, meta).map((opt) => opt.fold(() => entries, (entry) => [...entries, [`${prefix}.${key}`, entry]]))), Right([]));
 const validateAliases = (config) => {
 	const secretEntries = config.secret ?? {};
 	const envEntries = config.env ?? {};
-	const entries = /* @__PURE__ */ new Map();
-	const secretResults = Object.entries(secretEntries).map(([key, meta]) => [key, validateOneSecret(key, meta, secretEntries)]);
-	for (const [key, result] of secretResults) {
-		const outcome = result.fold((err) => err, (opt) => opt.orUndefined());
-		if (outcome === void 0) continue;
-		if ("_tag" in outcome) return Left(outcome);
-		entries.set(`secret.${key}`, outcome);
-	}
-	const envResults = Object.entries(envEntries).map(([key, meta]) => [key, validateOneEnv(key, meta, envEntries)]);
-	for (const [key, result] of envResults) {
-		const outcome = result.fold((err) => err, (opt) => opt.orUndefined());
-		if (outcome === void 0) continue;
-		if ("_tag" in outcome) return Left(outcome);
-		entries.set(`env.${key}`, outcome);
+	const secretPairs = collectValidated(Object.entries(secretEntries), (k, m) => validateOneSecret(k, m, secretEntries), "secret");
+	const envPairs = collectValidated(Object.entries(envEntries), (k, m) => validateOneEnv(k, m, envEntries), "env");
+	return secretPairs.flatMap((secrets) => envPairs.map((envs) => [...secrets, ...envs])).map((allEntries) => ({ entries: new Map(allEntries) }));
+};
+/** Format an alias error into a human-readable message */
+const formatAliasError = (error) => {
+	switch (error._tag) {
+		case "AliasInvalidSyntax": return `[${error.kind}.${error.key}] from_key = "${error.value}" — expected "secret.<KEY>" or "env.<KEY>"`;
+		case "AliasTargetMissing": return `[${error.key}] from_key target "${error.target}" not found in config`;
+		case "AliasSelfReference": return `[${error.key}] from_key cannot reference itself`;
+		case "AliasChained": return `[${error.key}] from_key target "${error.target}" is itself an alias; chained aliases are not supported`;
+		case "AliasCrossType": return `[${error.kind}.${error.key}] cannot alias a ${error.targetKind} entry; same-type aliasing only (secret→secret, env→env)`;
+		case "AliasValueConflict": return `[${error.kind}.${error.key}] cannot declare both from_key and ${error.field}; an alias has no value of its own`;
 	}
-	return Right({ entries });
 };
 //#endregion
 //#region src/core/keygen.ts
@@ -1197,11 +1199,12 @@ const sealSecrets = (meta, values, recipient) => {
 		message: "age CLI not found on PATH"
 	});
 	return Object.entries(meta).reduce((acc, [key, secretMeta]) => acc.flatMap((result) => {
-		if (!(key in values)) return Right({
+		const value = values[key];
+		if (value === void 0) return Right({
 			...result,
 			[key]: secretMeta
 		});
-		return ageEncrypt(values[key], recipient).mapLeft((err) => ({
+		return ageEncrypt(value, recipient).mapLeft((err) => ({
 			_tag: "EncryptFailed",
 			key,
 			message: err.message
@@ -1297,11 +1300,11 @@ const bootSafe = (options) => {
 		const secretEntries = config.secret ?? {};
 		const envEntries = config.env ?? {};
 		const nonAliasSecretEntries = Object.fromEntries(Object.entries(secretEntries).filter(([, meta]) => meta.from_key === void 0));
-		const aliasSecretKeys = Object.keys(secretEntries).filter((k) => secretEntries[k].from_key !== void 0);
+		const aliasSecretKeys = Object.entries(secretEntries).filter(([, meta]) => meta.from_key !== void 0).map(([k]) => k);
 		const nonAliasEnvEntries = Object.entries(envEntries).filter(([, meta]) => meta.from_key === void 0);
-		const aliasEnvKeys = Object.keys(envEntries).filter((k) => envEntries[k].from_key !== void 0);
+		const aliasEnvKeys = Object.entries(envEntries).filter(([, meta]) => meta.from_key !== void 0).map(([k]) => k);
 		const nonAliasMetaKeys = Object.keys(nonAliasSecretEntries);
-		const hasSealedValues = nonAliasMetaKeys.some((k) => !!nonAliasSecretEntries[k].encrypted_value);
+		const hasSealedValues = Object.values(nonAliasSecretEntries).some((meta) => !!meta.encrypted_value);
 		const identityKeyResult = resolveIdentityKey(config, configDir);
 		const identityKey = identityKeyResult.fold(() => Option(void 0), (k) => k);
 		if (identityKeyResult.isLeft() && !hasSealedValues) return identityKeyResult.fold((err) => Left(err), () => Left({
@@ -1314,7 +1317,7 @@ const bootSafe = (options) => {
 			const injected = [];
 			const skipped = [];
 			warnings.push(...checkEnvMisclassification(config));
-			const envDefaults = Object.fromEntries(nonAliasEnvEntries.flatMap(([key, entry]) => Option(process.env[key]).fold(() => entry.value !== void 0 ? [[key, entry.value]] : [], () => [])));
+			const envDefaults = Object.fromEntries(nonAliasEnvEntries.flatMap(([key, entry]) => Option(process.env[key]).fold(() => Option(entry.value).fold(() => [], (v) => [[key, v]]), () => [])));
 			const overridden = nonAliasEnvEntries.flatMap(([key]) => Option(process.env[key]).fold(() => [], () => [key]));
 			if (inject) Object.entries(envDefaults).forEach(([key, value]) => {
 				process.env[key] = value;
@@ -1374,21 +1377,20 @@ const bootSafe = (options) => {
 			aliasSecretKeys.forEach((aliasKey) => {
 				const entry = aliasTable.entries.get(`secret.${aliasKey}`);
 				if (!entry) return;
-				const targetValue = secrets[entry.targetKey];
-				if (targetValue !== void 0) {
-					secrets[aliasKey] = targetValue;
-					injected.push(aliasKey);
-					log.debug("phase.alias.copied", {
+				Option(secrets[entry.targetKey]).fold(() => {
+					skipped.push(aliasKey);
+					log.debug("phase.alias.target_unresolved", {
 						alias: aliasKey,
 						target: entry.targetKey
 					});
-				} else {
-					skipped.push(aliasKey);
-					log.debug("phase.alias.target_unresolved", {
+				}, (targetValue) => {
+					secrets[aliasKey] = targetValue;
+					injected.push(aliasKey);
+					log.debug("phase.alias.copied", {
 						alias: aliasKey,
 						target: entry.targetKey
 					});
-				}
+				});
 			});
 			aliasEnvKeys.forEach((aliasKey) => {
 				const entry = aliasTable.entries.get(`env.${aliasKey}`);
@@ -1425,7 +1427,7 @@ const bootSafe = (options) => {
 };
 //#endregion
 //#region src/core/patterns.ts
-const EXCLUDED_VARS = new Set([
+const EXCLUDED_VARS = Set$1([
 	"PATH",
 	"HOME",
 	"USER",
@@ -2138,25 +2140,22 @@ const envScan = (env, options) => {
 	};
 };
 const parseAliasRef = (raw, expectedKind) => {
-	const match = /^(secret|env)\.(.+)$/.exec(raw);
-	if (!match) return void 0;
-	if (match[1] !== expectedKind) return void 0;
-	return match[2];
+	const match = raw.match(/^(secret|env)\.(.+)$/);
+	if (match?.[1] !== expectedKind) return Option(void 0);
+	return Option(match[2]);
 };
 /** Bidirectional drift detection between config and live environment */
 const envCheck = (config, env) => {
 	const secretEntries = config.secret ?? {};
 	const metaKeys = Object.keys(secretEntries);
-	const trackedSet = new Set(metaKeys);
+	const metaKeysSet = Set$1(metaKeys);
 	const isSecretPresent = (key) => {
 		if (env[key] !== void 0 && env[key] !== "") return true;
 		const meta = secretEntries[key];
 		if (meta?.from_key === void 0) return false;
-		const targetKey = parseAliasRef(meta.from_key, "secret");
-		return targetKey !== void 0 && env[targetKey] !== void 0 && env[targetKey] !== "";
+		return parseAliasRef(meta.from_key, "secret").fold(() => false, (targetKey) => env[targetKey] !== void 0 && env[targetKey] !== "");
 	};
-	const secretDriftEntries = metaKeys.map((key) => {
-		const meta = secretEntries[key];
+	const secretDriftEntries = Object.entries(secretEntries).map(([key, meta]) => {
 		const present = isSecretPresent(key);
 		return {
 			envVar: key,
@@ -2170,14 +2169,9 @@ const envCheck = (config, env) => {
 		if (env[key] !== void 0 && env[key] !== "") return true;
 		const meta = envDefaults[key];
 		if (meta?.from_key === void 0) return false;
-		const targetKey = parseAliasRef(meta.from_key, "env");
-		return targetKey !== void 0 && env[targetKey] !== void 0 && env[targetKey] !== "";
+		return parseAliasRef(meta.from_key, "env").fold(() => false, (targetKey) => env[targetKey] !== void 0 && env[targetKey] !== "");
 	};
-	const envDefaultEntries = Object.keys(envDefaults).filter((key) => {
-		if (trackedSet.has(key)) return false;
-		trackedSet.add(key);
-		return true;
-	}).map((key) => {
+	const envDefaultEntries = Object.keys(envDefaults).filter((key) => !metaKeysSet.has(key)).map((key) => {
 		const present = isEnvPresent(key);
 		return {
 			envVar: key,
@@ -2186,7 +2180,8 @@ const envCheck = (config, env) => {
 			confidence: Option(void 0)
 		};
 	});
-	const untrackedEntries = scanEnv(env).filter((match) => !trackedSet.has(match.envVar)).map((match) => ({
+	const trackedKeys = Set$1([...metaKeys, ...envDefaultEntries.map((e) => e.envVar)]);
+	const untrackedEntries = scanEnv(env).filter((match) => !trackedKeys.has(match.envVar)).map((match) => ({
 		envVar: match.envVar,
 		service: match.service,
 		status: "untracked",
@@ -2229,6 +2224,22 @@ created = "${todayIso$1()}"
 //#region src/core/toml-edit.ts
 const SECTION_RE = /^\[.+\]\s*$/;
 const MULTILINE_OPEN = "\"\"\"";
+const scanSectionBoundary = (state, line, i) => {
+	if (state.done) return state;
+	if (state.inMultiline) return line.includes(MULTILINE_OPEN) ? {
+		...state,
+		inMultiline: false
+	} : state;
+	if (line.includes(MULTILINE_OPEN)) return (line.slice(line.indexOf("=") + 1).trim().match(/* @__PURE__ */ new RegExp("\"\"\"", "g")) ?? []).length === 1 ? {
+		...state,
+		inMultiline: true
+	} : state;
+	return SECTION_RE.test(line) ? {
+		...state,
+		end: i,
+		done: true
+	} : state;
+};
 /**
 * Find the line range [start, end) of a TOML section by its header string.
 * The range includes the header line through to (but not including) the next section header or EOF.
@@ -2237,26 +2248,14 @@ const MULTILINE_OPEN = "\"\"\"";
 const findSectionRange = (lines, sectionHeader) => {
 	const start = lines.findIndex((l) => l.trim() === sectionHeader);
 	if (start === -1) return void 0;
-	let end = lines.length;
-	let inMultiline = false;
-	for (let i = start + 1; i < lines.length; i++) {
-		const line = lines[i];
-		if (inMultiline) {
-			if (line.includes(MULTILINE_OPEN)) inMultiline = false;
-			continue;
-		}
-		if (line.includes(MULTILINE_OPEN)) {
-			if ((line.slice(line.indexOf("=") + 1).trim().match(/* @__PURE__ */ new RegExp("\"\"\"", "g")) ?? []).length === 1) inMultiline = true;
-			continue;
-		}
-		if (SECTION_RE.test(line)) {
-			end = i;
-			break;
-		}
-	}
+	const initial = {
+		end: lines.length,
+		inMultiline: false,
+		done: false
+	};
 	return {
 		start,
-		end
+		end: List(lines.slice(start + 1)).zipWithIndex().foldLeft(initial)((state, entry) => scanSectionBoundary(state, entry[0], start + 1 + entry[1])).end
 	};
 };
 /** Check whether a section header exists in the raw TOML */
@@ -2272,12 +2271,10 @@ const removeSection = (raw, sectionHeader) => {
 		_tag: "SectionNotFound",
 		section: sectionHeader
 	});
-	let removeEnd = range.end;
-	while (removeEnd > range.start && removeEnd - 1 >= range.start && lines[removeEnd - 1].trim() === "") removeEnd--;
-	const before = lines.slice(0, range.start);
 	const after = lines.slice(range.end);
-	while (before.length > 0 && before[before.length - 1].trim() === "") before.pop();
-	const result = [...before, ...after].join("\n");
+	const beforeAll = lines.slice(0, range.start);
+	const lastNonBlank = beforeAll.findLastIndex((l) => l.trim() !== "");
+	const result = [...lastNonBlank === -1 ? [] : beforeAll.slice(0, lastNonBlank + 1), ...after].join("\n");
 	return Either.right(result);
 };
 /**
@@ -2313,55 +2310,47 @@ const updateSectionFields = (raw, sectionHeader, updates) => {
 	const before = lines.slice(0, range.start + 1);
 	const after = lines.slice(range.end);
 	const sectionBody = lines.slice(range.start + 1, range.end);
-	const remaining = [];
-	const updatedKeys = /* @__PURE__ */ new Set();
-	let inMultiline = false;
-	let multilineKey = "";
-	for (let i = 0; i < sectionBody.length; i++) {
-		const line = sectionBody[i];
-		if (inMultiline) {
-			if (line.includes(MULTILINE_OPEN)) {
-				inMultiline = false;
-				if (updates[multilineKey] === null) continue;
-				if (multilineKey in updates) continue;
-			} else {
-				if (updates[multilineKey] === null) continue;
-				if (multilineKey in updates) continue;
-			}
-			remaining.push(line);
-			continue;
-		}
+	const findClosingMultiline = (fromIdx) => {
+		const idx = sectionBody.findIndex((l, j) => j > fromIdx && l.includes(MULTILINE_OPEN));
+		return idx === -1 ? sectionBody.length : idx;
+	};
+	const initial = {
+		remaining: [],
+		updatedKeys: Set$1.empty(),
+		skipUntil: -1
+	};
+	const step = (state, line, i) => {
+		if (i <= state.skipUntil) return state;
 		const eqIdx = line.indexOf("=");
-		if (eqIdx > 0 && !line.trimStart().startsWith("#") && !line.trimStart().startsWith("[")) {
-			const key = line.slice(0, eqIdx).trim();
-			if (key in updates) {
-				updatedKeys.add(key);
-				const afterEquals = line.slice(eqIdx + 1).trim();
-				if (afterEquals.includes(MULTILINE_OPEN)) {
-					if ((afterEquals.match(/* @__PURE__ */ new RegExp("\"\"\"", "g")) ?? []).length === 1) {
-						inMultiline = true;
-						multilineKey = key;
-					}
-				}
-				if (updates[key] === null) continue;
-				remaining.push(`${key} = ${updates[key]}`);
-				if (inMultiline) {
-					for (let j = i + 1; j < sectionBody.length; j++) if (sectionBody[j].includes(MULTILINE_OPEN)) {
-						i = j;
-						inMultiline = false;
-						break;
-					}
-				}
-				continue;
-			}
+		const isFieldLine = eqIdx > 0 && !line.trimStart().startsWith("#") && !line.trimStart().startsWith("[");
+		const key = isFieldLine ? line.slice(0, eqIdx).trim() : "";
+		if (isFieldLine && key in updates) {
+			const afterEquals = line.slice(eqIdx + 1).trim();
+			const skipUntil = afterEquals.includes(MULTILINE_OPEN) && (afterEquals.match(/* @__PURE__ */ new RegExp("\"\"\"", "g")) ?? []).length === 1 ? findClosingMultiline(i) : state.skipUntil;
+			const updatedKeys = state.updatedKeys.add(key);
+			const value = updates[key];
+			if (value === null) return {
+				...state,
+				updatedKeys,
+				skipUntil
+			};
+			return {
+				remaining: [...state.remaining, `${key} = ${value}`],
+				updatedKeys,
+				skipUntil
+			};
 		}
-		remaining.push(line);
-	}
-	const newFields = Object.entries(updates).filter(([key, value]) => value !== null && !updatedKeys.has(key)).map(([key, value]) => `${key} = ${value}`);
-	remaining.push(...newFields);
+		return {
+			...state,
+			remaining: [...state.remaining, line]
+		};
+	};
+	const final = List(sectionBody).zipWithIndex().foldLeft(initial)((state, entry) => step(state, entry[0], entry[1]));
+	const newFields = Object.entries(updates).filter(([key, value]) => value !== null && !final.updatedKeys.has(key)).map(([key, value]) => `${key} = ${value}`);
 	const result = [
 		...before,
-		...remaining,
+		...final.remaining,
+		...newFields,
 		...after
 	].join("\n");
 	return Either.right(result);
@@ -2372,6 +2361,60 @@ const updateSectionFields = (raw, sectionHeader, updates) => {
 */
 const appendSection = (raw, block) => `${raw.trimEnd()}\n\n${block}`;
 //#endregion
+//#region src/core/validate.ts
+/**
+* Validate a raw TOML string as a complete envpkt config: parse → schema → aliases.
+*
+* Used by write-path CLI commands to verify the post-edit file would still be
+* structurally valid before persisting. Catalog resolution is intentionally
+* excluded — catalog issues depend on external files, not on the local edit,
+* and `envpkt validate` covers them as a separate explicit check.
+*/
+const validateRawConfig = (raw) => parseToml(raw).flatMap(validateConfig).flatMap((config) => validateAliases(config).map(() => config));
+/** Human-readable one-liner for any ValidationError tag. */
+const formatValidationError = (err) => {
+	switch (err._tag) {
+		case "FileNotFound": return `Config file not found: ${err.path}`;
+		case "ParseError": return `TOML parse error: ${err.message}`;
+		case "ValidationError": return `Schema validation failed: ${err.errors.toArray().join("; ")}`;
+		case "ReadError": return `Read error: ${err.message}`;
+		case "AliasInvalidSyntax":
+		case "AliasTargetMissing":
+		case "AliasSelfReference":
+		case "AliasChained":
+		case "AliasCrossType":
+		case "AliasValueConflict": return formatAliasError(err);
+	}
+};
+//#endregion
+//#region src/cli/write-gate.ts
+/**
+* Run structural validation against an in-memory TOML string.
+* On failure, prints the error, leaves the file untouched, and exits with code 1.
+* On success, returns — caller is responsible for writing.
+*
+* Use this when the write step has bespoke logic (e.g. wraps writeFileSync in Try,
+* has multi-line post-write output). Otherwise prefer `writeIfValid`.
+*/
+const validateOrExit = (updated) => {
+	validateRawConfig(updated).fold((err) => {
+		console.error(`${RED}Error:${RESET} Aborted — change would produce an invalid config:`);
+		console.error(`  ${formatValidationError(err)}`);
+		console.error(`${DIM}File unchanged.${RESET}`);
+		process.exit(1);
+	}, () => {});
+};
+/**
+* Validate then persist. Most mutating CLI commands use this — it bundles the
+* validate-or-exit gate with the writeFileSync + success log so each call site
+* stays two lines instead of five.
+*/
+const writeIfValid = (configPath, updated, successMsg) => {
+	validateOrExit(updated);
+	writeFileSync(configPath, updated, "utf-8");
+	console.log(successMsg);
+};
+//#endregion
 //#region src/cli/commands/env.ts
 const printPostWriteGuidance = () => {
 	console.log(`\n${DIM}Note: Secret values are NOT stored — only metadata.${RESET}`);
@@ -2403,7 +2446,9 @@ const runEnvScan = (options) => {
 				return;
 			}
 			const newToml = generateTomlFromScan(newEntries);
-			Try(() => writeFileSync(configPath, `${existing.trimEnd()}\n\n${newToml}`, "utf-8")).fold((err) => {
+			const combined = `${existing.trimEnd()}\n\n${newToml}`;
+			validateOrExit(combined);
+			Try(() => writeFileSync(configPath, combined, "utf-8")).fold((err) => {
 				console.error(`\n${RED}Error:${RESET} Failed to write: ${err}`);
 				process.exit(1);
 			}, () => {
@@ -2411,8 +2456,9 @@ const runEnvScan = (options) => {
 				printPostWriteGuidance();
 			});
 		} else {
-			const header = `#:schema https://raw.githubusercontent.com/jordanburke/envpkt/main/schemas/envpkt.schema.json\n\nversion = 1\n\n[lifecycle]\nstale_warning_days = 90\n\n`;
-			Try(() => writeFileSync(configPath, header + toml, "utf-8")).fold((err) => {
+			const combined = `#:schema https://raw.githubusercontent.com/jordanburke/envpkt/main/schemas/envpkt.schema.json\n\nversion = 1\n\n[lifecycle]\nstale_warning_days = 90\n\n` + toml;
+			validateOrExit(combined);
+			Try(() => writeFileSync(configPath, combined, "utf-8")).fold((err) => {
 				console.error(`\n${RED}Error:${RESET} Failed to write: ${err}`);
 				process.exit(1);
 			}, () => {
@@ -2521,8 +2567,7 @@ const runEnvAdd = (name, value, options) => {
 				console.log(block);
 				return;
 			}
-			writeFileSync(configPath, appendSection(readFileSync(configPath, "utf-8"), block), "utf-8");
-			console.log(`${GREEN}✓${RESET} Added ${BOLD}${name}${RESET} to ${CYAN}${configPath}${RESET}`);
+			writeIfValid(configPath, appendSection(readFileSync(configPath, "utf-8"), block), `${GREEN}✓${RESET} Added ${BOLD}${name}${RESET} to ${CYAN}${configPath}${RESET}`);
 		});
 	});
 };
@@ -2557,8 +2602,7 @@ const runEnvEdit = (name, options) => {
 					console.log(updated);
 					return;
 				}
-				writeFileSync(configPath, updated, "utf-8");
-				console.log(`${GREEN}✓${RESET} Updated ${BOLD}${name}${RESET} in ${CYAN}${configPath}${RESET}`);
+				writeIfValid(configPath, updated, `${GREEN}✓${RESET} Updated ${BOLD}${name}${RESET} in ${CYAN}${configPath}${RESET}`);
 			});
 		});
 	});
@@ -2574,8 +2618,7 @@ const runEnvRm = (name, options) => {
 				console.log(updated);
 				return;
 			}
-			writeFileSync(configPath, updated, "utf-8");
-			console.log(`${GREEN}✓${RESET} Removed ${BOLD}${name}${RESET} from ${CYAN}${configPath}${RESET}`);
+			writeIfValid(configPath, updated, `${GREEN}✓${RESET} Removed ${BOLD}${name}${RESET} from ${CYAN}${configPath}${RESET}`);
 		});
 	});
 };
@@ -2645,8 +2688,7 @@ const runEnvAlias = (name, options) => {
 				return;
 			}
 			const raw = readFileSync(configPath, "utf-8");
-			writeFileSync(configPath, appendSection(existing ? removeSection(raw, `[env.${name}]`).fold(() => raw, (r) => r) : raw, block), "utf-8");
-			console.log(`${GREEN}✓${RESET} Aliased ${BOLD}${name}${RESET} → ${BOLD}${options.from}${RESET} in ${CYAN}${configPath}${RESET}`);
+			writeIfValid(configPath, appendSection(existing ? removeSection(raw, `[env.${name}]`).fold(() => raw, (r) => r) : raw, block), `${GREEN}✓${RESET} Aliased ${BOLD}${name}${RESET} → ${BOLD}${options.from}${RESET} in ${CYAN}${configPath}${RESET}`);
 		});
 	});
 };
@@ -2661,8 +2703,7 @@ const runEnvRename = (oldName, newName, options) => {
 				console.log(updated);
 				return;
 			}
-			writeFileSync(configPath, updated, "utf-8");
-			console.log(`${GREEN}✓${RESET} Renamed ${BOLD}${oldName}${RESET} → ${BOLD}${newName}${RESET} in ${CYAN}${configPath}${RESET}`);
+			writeIfValid(configPath, updated, `${GREEN}✓${RESET} Renamed ${BOLD}${oldName}${RESET} → ${BOLD}${newName}${RESET} in ${CYAN}${configPath}${RESET}`);
 		});
 	});
 };
@@ -2753,31 +2794,7 @@ const runExec = (args, options) => {
 //#endregion
 //#region src/core/fleet.ts
 const CONFIG_FILENAME$1 = "envpkt.toml";
-const SKIP_DIRS = new Set([
-	"node_modules",
-	".git",
-	".hg",
-	".svn",
-	"dist",
-	"build",
-	"lib",
-	".claude",
-	"__pycache__",
-	"target",
-	"out",
-	"tmp",
-	".terraform",
-	".gradle",
-	".cargo",
-	".venv",
-	".next",
-	".cache",
-	".tox",
-	"vendor",
-	"coverage",
-	".nyc_output",
-	".turbo"
-]);
+const SKIP_DIRS = Set$1.of("node_modules", ".git", ".hg", ".svn", "dist", "build", "lib", ".claude", "__pycache__", "target", "out", "tmp", ".terraform", ".gradle", ".cargo", ".venv", ".next", ".cache", ".tox", "vendor", "coverage", ".nyc_output", ".turbo");
 function* findEnvpktFiles(dir, maxDepth, currentDepth = 0) {
 	if (currentDepth > maxDepth) return;
 	const configPath = join(dir, CONFIG_FILENAME$1);
@@ -2942,6 +2959,7 @@ const runInit = (dir, options) => {
 		}, (keys) => keys);
 	});
 	const content = generateTemplate(options, fnoxKeys.orUndefined());
+	validateOrExit(content);
 	Try(() => writeFileSync(outPath, content, "utf-8")).fold((err) => {
 		console.error(`${RED}Error:${RESET} Failed to write ${CONFIG_FILENAME}: ${err}`);
 		process.exit(1);
@@ -3364,24 +3382,19 @@ const handleGetSecretMeta = (args) => {
 	const secretEntries = config.secret ?? {};
 	return Option(secretEntries[key]).fold(() => errorResult(`Secret not found: ${key}`), (meta) => {
 		const { encrypted_value: _, from_key: fromKey, ...rest } = meta;
-		if (fromKey !== void 0) {
-			const targetKey = /^secret\.(.+)$/.exec(fromKey)?.[1];
-			const target = targetKey !== void 0 ? secretEntries[targetKey] : void 0;
-			if (target) {
-				const { encrypted_value: __, from_key: ___, ...targetRest } = target;
-				return textResult(JSON.stringify({
-					key,
-					...targetRest,
-					...rest,
-					alias_of: fromKey
-				}, null, 2));
-			}
+		if (fromKey !== void 0) return Option(fromKey.match(/^secret\.(.+)$/)?.[1]).flatMap((k) => Option(secretEntries[k])).fold(() => textResult(JSON.stringify({
+			key,
+			...rest,
+			alias_of: fromKey
+		}, null, 2)), (t) => {
+			const { encrypted_value: __, from_key: ___, ...targetRest } = t;
 			return textResult(JSON.stringify({
 				key,
+				...targetRest,
 				...rest,
 				alias_of: fromKey
 			}, null, 2));
-		}
+		});
 		return textResult(JSON.stringify({
 			key,
 			...rest
@@ -3540,75 +3553,105 @@ const resolveValues = async (keys, profile, agentKey) => {
 };
 //#endregion
 //#region src/cli/commands/seal.ts
-/** Write sealed values back into the TOML file, preserving structure */
-const writeSealedToml = (configPath, sealedMeta) => {
-	const lines = readFileSync(configPath, "utf-8").split("\n");
-	const output = [];
-	let currentMetaKey = Option.none();
-	let insideMetaBlock = false;
-	let hasEncryptedValue = false;
-	const pendingSeals = /* @__PURE__ */ new Map();
-	Object.entries(sealedMeta).forEach(([key, meta]) => {
-		if (meta.encrypted_value) pendingSeals.set(key, meta.encrypted_value);
+const META_SECTION_RE = /^\[secret\.(.+)\]\s*$/;
+const ENCRYPTED_VALUE_RE = /^encrypted_value\s*=/;
+const NEW_SECTION_RE = /^\[/;
+const MULTILINE_DELIM = "\"\"\"";
+/**
+* In-memory transform: inject sealed encrypted_value blocks into raw TOML,
+* replacing existing encrypted_value lines (single or multiline) or appending
+* a new block at the end of the section. Pure — no I/O.
+*/
+const applySealedToml = (raw, sealedMeta) => {
+	const lines = raw.split("\n");
+	const getSeal = (key) => Option(sealedMeta[key]?.encrypted_value);
+	const isPending = (state, key) => !getSeal(key).isEmpty && !state.consumedKeys.has(key);
+	const sealLinesFor = (key) => getSeal(key).fold(() => [], (v) => [
+		`encrypted_value = """`,
+		v,
+		`"""`
+	]);
+	/** Append a seal block to `output` if the current section is pending and hasn't already got one. */
+	const flushPending = (state) => state.currentMetaKey.fold(() => state, (key) => {
+		if (state.hasEncryptedValue || !isPending(state, key)) return state;
+		return {
+			...state,
+			output: [
+				...state.output,
+				...sealLinesFor(key),
+				""
+			],
+			consumedKeys: state.consumedKeys.add(key)
+		};
 	});
-	const metaSectionRe = /^\[secret\.(.+)\]\s*$/;
-	const encryptedValueRe = /^encrypted_value\s*=/;
-	const newSectionRe = /^\[/;
-	const flushPending = () => {
-		currentMetaKey.forEach((key) => {
-			if (!hasEncryptedValue && pendingSeals.has(key)) {
-				output.push(`encrypted_value = """`);
-				output.push(pendingSeals.get(key));
-				output.push(`"""`);
-				output.push("");
-				pendingSeals.delete(key);
-			}
-		});
-	};
-	for (let i = 0; i < lines.length; i++) {
-		const line = lines[i];
-		const metaMatch = metaSectionRe.exec(line);
+	const step = (state, line, i) => {
+		if (i <= state.skipUntil) return state;
+		const metaMatch = line.match(META_SECTION_RE);
 		if (metaMatch) {
-			flushPending();
-			currentMetaKey = Option(metaMatch[1]);
-			insideMetaBlock = true;
-			hasEncryptedValue = false;
-			output.push(line);
-			continue;
+			const flushed = flushPending(state);
+			return {
+				...flushed,
+				output: [...flushed.output, line],
+				currentMetaKey: Option(metaMatch[1]),
+				insideMetaBlock: true,
+				hasEncryptedValue: false
+			};
 		}
-		if (insideMetaBlock && newSectionRe.test(line) && !metaSectionRe.test(line)) {
-			flushPending();
-			insideMetaBlock = false;
-			currentMetaKey = Option.none();
-			output.push(line);
-			continue;
+		if (state.insideMetaBlock && NEW_SECTION_RE.test(line) && !META_SECTION_RE.test(line)) {
+			const flushed = flushPending(state);
+			return {
+				...flushed,
+				output: [...flushed.output, line],
+				insideMetaBlock: false,
+				currentMetaKey: Option.none()
+			};
 		}
-		if (insideMetaBlock && encryptedValueRe.test(line)) {
-			hasEncryptedValue = true;
-			const replacing = currentMetaKey.fold(() => false, (key) => pendingSeals.has(key));
-			if (replacing) currentMetaKey.forEach((key) => {
-				output.push(`encrypted_value = """`);
-				output.push(pendingSeals.get(key));
-				output.push(`"""`);
-				pendingSeals.delete(key);
-			});
-			else output.push(line);
-			if (line.slice(line.indexOf("=") + 1).trim().includes("\"\"\"")) {
-				while (i + 1 < lines.length && !lines[i + 1].includes("\"\"\"")) {
-					if (!replacing) output.push(lines[i + 1]);
-					i++;
-				}
-				if (i + 1 < lines.length) {
-					if (!replacing) output.push(lines[i + 1]);
-					i++;
-				}
-			}
-			continue;
+		if (state.insideMetaBlock && ENCRYPTED_VALUE_RE.test(line)) {
+			const replacingKey = state.currentMetaKey.filter((k) => isPending(state, k));
+			const replacement = replacingKey.fold(() => [line], (key) => sealLinesFor(key));
+			const consumedKeys = replacingKey.fold(() => state.consumedKeys, (key) => state.consumedKeys.add(key));
+			const replacing = !replacingKey.isEmpty;
+			if (!line.slice(line.indexOf("=") + 1).trim().includes(MULTILINE_DELIM)) return {
+				...state,
+				output: [...state.output, ...replacement],
+				hasEncryptedValue: true,
+				consumedKeys
+			};
+			const closingIdx = lines.findIndex((l, j) => j > i && l.includes(MULTILINE_DELIM));
+			const effectiveEnd = closingIdx === -1 ? lines.length - 1 : closingIdx;
+			const continuation = replacing ? [] : lines.slice(i + 1, effectiveEnd + 1);
+			return {
+				...state,
+				output: [
+					...state.output,
+					...replacement,
+					...continuation
+				],
+				hasEncryptedValue: true,
+				consumedKeys,
+				skipUntil: effectiveEnd
+			};
 		}
-		output.push(line);
-	}
-	flushPending();
-	writeFileSync(configPath, output.join("\n"));
+		return {
+			...state,
+			output: [...state.output, line]
+		};
+	};
+	const initial = {
+		output: [],
+		currentMetaKey: Option.none(),
+		insideMetaBlock: false,
+		hasEncryptedValue: false,
+		consumedKeys: Set$1.empty(),
+		skipUntil: -1
+	};
+	return flushPending(List(lines).zipWithIndex().foldLeft(initial)((state, entry) => step(state, entry[0], entry[1]))).output.join("\n");
+};
+/** Write sealed values back into the TOML file, preserving structure. */
+const writeSealedToml = (configPath, sealedMeta) => {
+	const finalContent = applySealedToml(readFileSync(configPath, "utf-8"), sealedMeta);
+	validateOrExit(finalContent);
+	writeFileSync(configPath, finalContent);
 };
 const runSeal = async (options) => {
 	const { path: configPath, source: configSource } = resolveConfigPath(options.config).fold((err) => {
@@ -3846,8 +3889,7 @@ const runSecretAdd = (name, options) => {
 				console.log(block);
 				return;
 			}
-			writeFileSync(configPath, appendSection(readFileSync(configPath, "utf-8"), block), "utf-8");
-			console.log(`${GREEN}✓${RESET} Added ${BOLD}${name}${RESET} to ${CYAN}${configPath}${RESET}`);
+			writeIfValid(configPath, appendSection(readFileSync(configPath, "utf-8"), block), `${GREEN}✓${RESET} Added ${BOLD}${name}${RESET} to ${CYAN}${configPath}${RESET}`);
 		});
 	});
 };
@@ -3879,8 +3921,7 @@ const runSecretEdit = (name, options) => {
 					console.log(updated);
 					return;
 				}
-				writeFileSync(configPath, updated, "utf-8");
-				console.log(`${GREEN}✓${RESET} Updated ${BOLD}${name}${RESET} in ${CYAN}${configPath}${RESET}`);
+				writeIfValid(configPath, updated, `${GREEN}✓${RESET} Updated ${BOLD}${name}${RESET} in ${CYAN}${configPath}${RESET}`);
 			});
 		});
 	});
@@ -3896,8 +3937,7 @@ const runSecretRm = (name, options) => {
 				console.log(updated);
 				return;
 			}
-			writeFileSync(configPath, updated, "utf-8");
-			console.log(`${GREEN}✓${RESET} Removed ${BOLD}${name}${RESET} from ${CYAN}${configPath}${RESET}`);
+			writeIfValid(configPath, updated, `${GREEN}✓${RESET} Removed ${BOLD}${name}${RESET} from ${CYAN}${configPath}${RESET}`);
 		});
 	});
 };
@@ -3912,8 +3952,7 @@ const runSecretRename = (oldName, newName, options) => {
 				console.log(updated);
 				return;
 			}
-			writeFileSync(configPath, updated, "utf-8");
-			console.log(`${GREEN}✓${RESET} Renamed ${BOLD}${oldName}${RESET} → ${BOLD}${newName}${RESET} in ${CYAN}${configPath}${RESET}`);
+			writeIfValid(configPath, updated, `${GREEN}✓${RESET} Renamed ${BOLD}${oldName}${RESET} → ${BOLD}${newName}${RESET} in ${CYAN}${configPath}${RESET}`);
 		});
 	});
 };
@@ -3983,11 +4022,102 @@ const runSecretAlias = (name, options) => {
 				return;
 			}
 			const raw = readFileSync(configPath, "utf-8");
-			writeFileSync(configPath, appendSection(existing ? removeSection(raw, `[secret.${name}]`).fold(() => raw, (r) => r) : raw, block), "utf-8");
-			console.log(`${GREEN}✓${RESET} Aliased ${BOLD}${name}${RESET} → ${BOLD}${options.from}${RESET} in ${CYAN}${configPath}${RESET}`);
+			writeIfValid(configPath, appendSection(existing ? removeSection(raw, `[secret.${name}]`).fold(() => raw, (r) => r) : raw, block), `${GREEN}✓${RESET} Aliased ${BOLD}${name}${RESET} → ${BOLD}${options.from}${RESET} in ${CYAN}${configPath}${RESET}`);
+		});
+	});
+};
+const readNewValue = async (key) => {
+	if (!process.stdin.isTTY) {
+		const chunks = [];
+		return new Promise((resolveP, rejectP) => {
+			process.stdin.on("data", (c) => chunks.push(Buffer.from(c)));
+			process.stdin.on("end", () => resolveP(Buffer.concat(chunks).toString("utf-8").replace(/\r?\n$/, "")));
+			process.stdin.on("error", rejectP);
+		});
+	}
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stderr
+	});
+	return new Promise((resolveP) => {
+		rl.question(`Enter new value for ${key}: `, (answer) => {
+			rl.close();
+			resolveP(answer);
 		});
 	});
 };
+const runSecretRotate = async (name, options) => {
+	const { configPath, source } = resolveConfigPath(options.config).fold((err) => {
+		console.error(formatError(err));
+		process.exit(2);
+		return {
+			configPath: "",
+			source: "flag"
+		};
+	}, ({ path, source: s }) => ({
+		configPath: path,
+		source: s
+	}));
+	const sourceMsg = formatConfigSource(configPath, source);
+	if (sourceMsg) console.error(sourceMsg);
+	const config = loadConfig(configPath).fold((err) => {
+		console.error(formatError(err));
+		process.exit(2);
+	}, (c) => c);
+	const meta = config.secret?.[name];
+	if (!meta) {
+		console.error(`${RED}Error:${RESET} Secret "${name}" not found in ${configPath}`);
+		process.exit(1);
+	}
+	if (meta.from_key) {
+		console.error(`${RED}Error:${RESET} "${name}" is an alias (from_key = "${meta.from_key}"). Rotate the target secret instead.`);
+		process.exit(1);
+	}
+	const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+	const wasSealed = !!meta.encrypted_value;
+	const raw = readFileSync(configPath, "utf-8");
+	if (!wasSealed) {
+		updateSectionFields(raw, `[secret.${name}]`, { last_rotated_at: `"${today}"` }).fold((err) => {
+			console.error(`${RED}Error:${RESET} ${err._tag}: ${err.section}`);
+			process.exit(2);
+		}, (result) => {
+			if (options.dryRun) {
+				console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
+				console.log(result);
+				return;
+			}
+			writeIfValid(configPath, result, `${GREEN}✓${RESET} Stamped ${BOLD}last_rotated_at${RESET} on ${BOLD}${name}${RESET} (unsealed — no ciphertext to update)`);
+		});
+		return;
+	}
+	if (!config.identity?.recipient) {
+		console.error(`${RED}Error:${RESET} identity.recipient is required to rotate a sealed secret`);
+		console.error(`${DIM}Run ${CYAN}envpkt keygen${DIM} to configure one.${RESET}`);
+		process.exit(2);
+	}
+	const { recipient } = config.identity;
+	const value = await readNewValue(name);
+	if (value === "") {
+		console.error(`${YELLOW}Cancelled:${RESET} no value provided — ${BOLD}${name}${RESET} was not rotated.`);
+		process.exit(1);
+	}
+	const ciphertext = ageEncrypt(value, recipient).fold((err) => {
+		console.error(`${RED}Error:${RESET} Encryption failed: ${err.message}`);
+		process.exit(2);
+		return "";
+	}, (ct) => ct);
+	updateSectionFields(applySealedToml(raw, { [name]: { encrypted_value: ciphertext } }), `[secret.${name}]`, { last_rotated_at: `"${today}"` }).fold((err) => {
+		console.error(`${RED}Error:${RESET} ${err._tag}: ${err.section}`);
+		process.exit(2);
+	}, (result) => {
+		if (options.dryRun) {
+			console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
+			console.log(result);
+			return;
+		}
+		writeIfValid(configPath, result, `${GREEN}✓${RESET} Rotated ${BOLD}${name}${RESET} (resealed + stamped ${CYAN}${today}${RESET})`);
+	});
+};
 const addSecretFlags = (cmd) => cmd.option("--service <service>", "Service this secret authenticates to").option("--purpose <purpose>", "Why this secret exists").option("--comment <comment>", "Free-form annotation").option("--expires <date>", "Expiration date (YYYY-MM-DD)").option("--capabilities <caps>", "Comma-separated capabilities (e.g. read,write)").option("--rotates <schedule>", "Rotation schedule (e.g. 90d, quarterly)").option("--rate-limit <limit>", "Rate limit info (e.g. 1000/min)").option("--model-hint <hint>", "Suggested model or tier").option("--source <source>", "Where the value originates (e.g. vault, ci)").option("--rotation-url <url>", "URL for secret rotation procedure").option("--tags <tags>", "Comma-separated key=value tags (e.g. env=prod,team=payments)");
 const registerSecretCommands = (program) => {
 	const secret = program.command("secret").description("Manage secret entries in envpkt.toml");
@@ -4003,6 +4133,9 @@ const registerSecretCommands = (program) => {
 	secret.command("rename").description("Rename a secret entry, preserving all metadata").argument("<old>", "Current secret name").argument("<new>", "New secret name").option("-c, --config <path>", "Path to envpkt.toml").option("--dry-run", "Preview the result without writing").action((oldName, newName, options) => {
 		runSecretRename(oldName, newName, options);
 	});
+	secret.command("rotate").description("Rotate a secret's value (sealed: reseal + stamp; unsealed: stamp only)").argument("<name>", "Secret name to rotate").option("-c, --config <path>", "Path to envpkt.toml").option("--dry-run", "Preview the result without writing").action(async (name, options) => {
+		await runSecretRotate(name, options);
+	});
 	secret.command("alias").description("Create an alias entry that reuses another secret's resolved value").argument("<name>", "Alias name (becomes the env var key)").requiredOption("--from <ref>", "Target reference — must be \"secret.<KEY>\"").option("-c, --config <path>", "Path to envpkt.toml").option("--purpose <purpose>", "Why this alias exists (local metadata)").option("--comment <comment>", "Free-form annotation").option("--tags <tags>", "Comma-separated key=value tags (e.g. env=prod,team=payments)").option("--force", "Overwrite the entry if <name> already exists").option("--dry-run", "Preview the TOML block without writing").action((name, options) => {
 		runSecretAlias(name, options);
 	});
@@ -4102,6 +4235,192 @@ const runUpgrade = () => {
 	else console.log(`\n${GREEN}✓${RESET} Upgraded ${YELLOW}${before}${RESET} → ${BOLD}${after}${RESET}`);
 };
 //#endregion
+//#region src/cli/commands/validate.ts
+const SEAL_BEGIN = "-----BEGIN AGE ENCRYPTED FILE-----";
+const SEAL_END = "-----END AGE ENCRYPTED FILE-----";
+const CHECK_NAMES = {
+	toml: "TOML syntax",
+	schema: "Schema",
+	catalog: "Catalog",
+	aliases: "Aliases",
+	sealed: "Sealed blocks"
+};
+/** Structural sanity scan over each [secret.*].encrypted_value PEM block. No decryption. */
+const checkSealedBlocks = (config) => {
+	const secrets = config.secret ?? {};
+	const sealed = Object.entries(secrets).filter(([, meta]) => typeof meta.encrypted_value === "string");
+	if (sealed.length === 0) return {
+		name: CHECK_NAMES.sealed,
+		status: "na",
+		detail: "no sealed values"
+	};
+	const broken = sealed.flatMap(([key, meta]) => {
+		const raw = (meta.encrypted_value ?? "").trim();
+		if (!raw.startsWith(SEAL_BEGIN)) return [`[secret.${key}] encrypted_value missing BEGIN marker`];
+		if (!raw.endsWith(SEAL_END)) return [`[secret.${key}] encrypted_value missing END marker`];
+		return [];
+	});
+	if (broken.length === 0) return {
+		name: CHECK_NAMES.sealed,
+		status: "ok",
+		detail: `${sealed.length} sealed value(s)`
+	};
+	return {
+		name: CHECK_NAMES.sealed,
+		status: "failed",
+		error: broken.join("; ")
+	};
+};
+const skipped = (name) => ({
+	name,
+	status: "skipped"
+});
+const buildReport = (path, raw) => {
+	return parseToml(raw).fold((err) => ({
+		ok: false,
+		configPath: path,
+		checks: [
+			{
+				name: CHECK_NAMES.toml,
+				status: "failed",
+				error: formatValidationError(err)
+			},
+			skipped(CHECK_NAMES.schema),
+			skipped(CHECK_NAMES.catalog),
+			skipped(CHECK_NAMES.aliases),
+			skipped(CHECK_NAMES.sealed)
+		]
+	}), (data) => {
+		const tomlOk = {
+			name: CHECK_NAMES.toml,
+			status: "ok"
+		};
+		return validateConfig(data).fold((err) => ({
+			ok: false,
+			configPath: path,
+			checks: [
+				tomlOk,
+				{
+					name: CHECK_NAMES.schema,
+					status: "failed",
+					error: formatValidationError(err)
+				},
+				skipped(CHECK_NAMES.catalog),
+				skipped(CHECK_NAMES.aliases),
+				skipped(CHECK_NAMES.sealed)
+			]
+		}), (config) => {
+			const checks = [
+				tomlOk,
+				{
+					name: CHECK_NAMES.schema,
+					status: "ok"
+				},
+				config.catalog ? resolveConfig(config, dirname(path)).fold((err) => ({
+					name: CHECK_NAMES.catalog,
+					status: "failed",
+					error: formatError(err)
+				}), () => ({
+					name: CHECK_NAMES.catalog,
+					status: "ok",
+					detail: config.catalog
+				})) : {
+					name: CHECK_NAMES.catalog,
+					status: "na",
+					detail: "no catalog declared"
+				},
+				validateAliases(config).fold((err) => ({
+					name: CHECK_NAMES.aliases,
+					status: "failed",
+					error: formatValidationError(err)
+				}), (table) => ({
+					name: CHECK_NAMES.aliases,
+					status: "ok",
+					detail: `${table.entries.size} alias(es)`
+				})),
+				checkSealedBlocks(config)
+			];
+			return {
+				ok: checks.every((c) => c.status === "ok" || c.status === "na"),
+				configPath: path,
+				checks
+			};
+		});
+	});
+};
+const renderCheckLines = (check) => {
+	switch (check.status) {
+		case "ok": {
+			const detail = check.detail ? ` ${DIM}(${check.detail})${RESET}` : "";
+			return [`  ${GREEN}✓${RESET} ${check.name}${detail}`];
+		}
+		case "failed": return check.error ? [`  ${RED}✗${RESET} ${check.name}`, `      ${RED}${check.error}${RESET}`] : [`  ${RED}✗${RESET} ${check.name}`];
+		case "skipped": return [`  ${DIM}○ ${check.name} (skipped — prior check failed)${RESET}`];
+		case "na": return [`  ${DIM}— ${check.name} (${check.detail ?? "not applicable"})${RESET}`];
+	}
+};
+const formatTextReport = (report, sourceMsg) => {
+	const header = `${report.ok ? `${GREEN}✓${RESET}` : `${RED}✗${RESET}`} ${BOLD}${report.ok ? `${GREEN}VALID${RESET}` : `${RED}INVALID${RESET}`}${RESET} — ${CYAN}${report.configPath}${RESET}`;
+	const checkLines = report.checks.flatMap((c) => [...renderCheckLines(c)]);
+	return [
+		...sourceMsg ? [sourceMsg] : [],
+		header,
+		"",
+		...checkLines
+	].join("\n");
+};
+const formatJsonReport = (report) => JSON.stringify({
+	ok: report.ok,
+	configPath: report.configPath,
+	checks: report.checks.map((c) => ({
+		name: c.name,
+		status: c.status,
+		error: c.error ?? null,
+		detail: c.detail ?? null
+	}))
+}, null, 2);
+const emit = (report, sourceMsg, asJson) => {
+	if (asJson) {
+		console.log(formatJsonReport(report));
+		return;
+	}
+	if (report.ok) console.log(formatTextReport(report, sourceMsg));
+	else console.error(formatTextReport(report, sourceMsg));
+};
+const runValidate = (options) => {
+	resolveConfigPath(options.config).fold((err) => {
+		if (options.json) console.log(JSON.stringify({
+			ok: false,
+			configPath: "path" in err ? err.path : null,
+			checks: [{
+				name: "Config file",
+				status: "failed",
+				error: formatValidationError(err)
+			}]
+		}, null, 2));
+		else console.error(formatError(err));
+		process.exit(2);
+	}, ({ path, source }) => {
+		const sourceMsg = formatConfigSource(path, source);
+		Try(() => readFileSync(path, "utf-8")).fold((e) => {
+			emit({
+				ok: false,
+				configPath: path,
+				checks: [{
+					name: "Read",
+					status: "failed",
+					error: e.message
+				}]
+			}, sourceMsg, options.json === true);
+			process.exit(2);
+		}, (raw) => {
+			const report = buildReport(path, raw);
+			emit(report, sourceMsg, options.json === true);
+			process.exit(report.ok ? 0 : 1);
+		});
+	});
+};
+//#endregion
 //#region src/cli/index.ts
 const program = new Command();
 program.name("envpkt").description("Credential lifecycle and fleet management for AI agents\n\n  Developer workflow:  env scan → keygen → seal → eval $(envpkt env export)\n  Agent / CI workflow: catalog → audit --strict → seal → exec --strict → fleet").version((() => {
@@ -4125,6 +4444,9 @@ program.command("audit").description("Audit credential health from envpkt.toml (
 program.command("fleet").description("Scan directory tree for envpkt.toml files and aggregate health (use in CI for fleet-wide monitoring)").option("-d, --dir <path>", "Root directory to scan", ".").option("--depth <n>", "Max directory depth", parseInt).option("--format <format>", "Output format: table | json", "table").option("--status <status>", "Filter agents by health status").action((options) => {
 	runFleet(options);
 });
+program.command("validate").description("Verify envpkt.toml integrity — runs TOML syntax, schema, catalog, alias, and sealed-block structural checks").option("-c, --config <path>", "Path to envpkt.toml").option("--json", "Output structured JSON instead of human-readable text").action((options) => {
+	runValidate(options);
+});
 program.command("inspect").description("Display structured view of envpkt.toml").option("-c, --config <path>", "Path to envpkt.toml").option("--format <format>", "Output format: table | json", "table").option("--resolved", "Show resolved view (catalog merged)").option("--secrets", "Show secret values from environment (masked by default)").option("--plaintext", "Show secret values in plaintext (requires --secrets)").action((options) => {
 	runInspect(options);
 });