@go-to-k/cdkd 0.219.9 → 0.220.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { A as withErrorHandling, B as generateResourceNameWithFallback, C as StackHasActiveImportsError, F as getLiveRenderer, H as withStackName, I as PATTERN_B_NAME_PROPERTIES, L as PATTERN_B_RESOURCE_TYPES, M as getLogger, P as runStackBuffered, S as ResourceUpdateNotSupportedError, V as withSkipPrefix, _ as MissingCdkCliError, a as assertRegionMatch, b as ProvisioningError, f as LocalInvokeBuildError$1, i as resolveExplicitPhysicalId, k as normalizeAwsError, l as CdkdError, m as LocalStartServiceError, n as matchesCdkPath, o as disableInstanceApiTermination, p as LocalMigrateError, r as normalizeAwsTagsToCfn, s as isTerminationProtectionPropagationError, t as CDK_PATH_TAG, v as NestedStackChildDirectDestroyError, w as StackTerminationProtectionError, x as ResourceTimeoutError, y as PartialFailureError, z as generateResourceName } from "./import-helpers-wLipXr5g.js";
 import { a as setAwsClients, i as resetAwsClients, r as getAwsClients, t as AwsClients } from "./aws-clients-pjPwZz1r.js";
-import { A as WorkGraph, B as resolveCaptureObservedState, C as DagBuilder, D as shouldRetainResource, E as S3StateBackend, F as runDockerStreaming, G as CFN_TEMPLATE_BODY_LIMIT, H as resolveStateBucketWithDefault, I as Synthesizer, J as findLargeInlineResources, K as CFN_TEMPLATE_URL_LIMIT, L as getDefaultStateBucketName, M as formatDockerLoginError, N as getDockerCmd, O as AssetPublisher, P as runDockerForeground, Q as resolveBucketRegion, R as getLegacyStateBucketName, S as DiffCalculator, T as LockManager, U as resolveStateBucketWithDefaultAndSource, V as resolveSkipPrefix, W as warnDeprecatedNoPrefixCliFlag, X as AssemblyReader, Y as uploadCfnTemplate, _ as ProviderRegistry, a as withRetry, b as IntrinsicFunctionResolver, c as formatResourceLine, d as gray, f as green, g as collectInlinePolicyNamesManagedBySiblings, h as IAMRoleProvider, i as withResourceDeadline, j as buildDockerImage, k as stringifyValue, l as bold, m as yellow, n as DEFAULT_RESOURCE_WARN_AFTER_MS, o as isRetryableTransientError, p as red, q as MIGRATE_TMP_PREFIX, r as DeployEngine, s as IMPLICIT_DELETE_DEPENDENCIES, t as DEFAULT_RESOURCE_TIMEOUT_MS, u as cyan, v as findActionableSilentDrops, w as TemplateParser, x as applyRoleArnIfSet, y as CloudControlProvider, z as resolveApp } from "./deploy-engine-DVP4vDXG.js";
+import { $ as resolveBucketRegion, A as stringifyValue, B as resolveApp, C as DiffCalculator, D as S3StateBackend, E as LockManager, F as runDockerForeground, G as warnDeprecatedNoPrefixCliFlag, H as resolveSkipPrefix, I as runDockerStreaming, J as MIGRATE_TMP_PREFIX, K as CFN_TEMPLATE_BODY_LIMIT, L as Synthesizer, M as buildDockerImage, N as formatDockerLoginError, O as shouldRetainResource, P as getDockerCmd, R as getDefaultStateBucketName, S as applyRoleArnIfSet, T as TemplateParser, U as resolveStateBucketWithDefault, V as resolveCaptureObservedState, W as resolveStateBucketWithDefaultAndSource, X as uploadCfnTemplate, Y as findLargeInlineResources, Z as AssemblyReader, _ as collectInlinePolicyNamesManagedBySiblings, a as withRetry, b as CloudControlProvider, c as extractDeploymentEventError, d as cyan, f as gray, g as IAMRoleProvider, h as yellow, i as withResourceDeadline, j as WorkGraph, k as AssetPublisher, l as formatResourceLine, m as red, n as DEFAULT_RESOURCE_WARN_AFTER_MS, o as isRetryableTransientError, p as green, q as CFN_TEMPLATE_URL_LIMIT, r as DeployEngine, s as IMPLICIT_DELETE_DEPENDENCIES, t as DEFAULT_RESOURCE_TIMEOUT_MS, u as bold, v as ProviderRegistry, w as DagBuilder, x as IntrinsicFunctionResolver, y as findActionableSilentDrops, z as getLegacyStateBucketName } from "./deploy-engine-CFaK71E9.js";
 import { t as ASGProvider } from "./asg-provider-B_hrCxRx.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomBytes, randomUUID } from "node:crypto";
@@ -1507,6 +1507,387 @@ async function promptRecreateConfirm(input) {
 	}
 }
 
+//#endregion
+//#region src/state/deployment-events-store.ts
+/**
+* Deployment-events store (issue #808) — persists the structured
+* deployment events emitted by the deploy engine / destroy runner as
+* JSONL to the state bucket, plus a small per-stack run index:
+*
+* - Events: `{prefix}/{stackName}/{region}/deployments/{runId}.jsonl`
+* - Index:  `{prefix}/{stackName}/{region}/deployments/index.json`
+*
+* Design constraints (all load-bearing):
+*
+* - **Best-effort, never blocking**: `record()` is synchronous and only
+*   buffers in memory; flushes run asynchronously (debounced timer +
+*   size threshold) and are serialized on a write chain. A failed S3
+*   write warns once and degrades to debug-level afterwards — it can
+*   NEVER fail or block the deploy/destroy itself.
+* - **No locking**: each run writes to its own unique `{runId}.jsonl`
+*   key (no concurrent writer by construction). `index.json` is
+*   last-writer-wins — acceptable for a derived view; the `.jsonl`
+*   files are the source of truth and `cdkd events` can read a run
+*   directly by id even if the index lost the race.
+* - **No resource properties** in events — errors + metadata only
+*   (properties may contain secrets and already live in state.json).
+* - **Separate keys from state.json** — no state schema bump; event
+*   files survive `cdkd destroy` (state deletion does not touch
+*   `deployments/`), preserving post-mortem context.
+*/
+/** Max runs retained in `deployments/index.json` (newest first). */
+const DEPLOYMENT_EVENTS_MAX_INDEX_RUNS = 20;
+/** Debounce window between buffered events and the async S3 flush. */
+const FLUSH_INTERVAL_MS = 2e3;
+/** Flush immediately once this many events are buffered. */
+const FLUSH_EVENT_THRESHOLD = 50;
+/** Build-time cdkd version, with a dev fallback for non-built contexts. */
+function getCdkdVersion() {
+	return "0.220.0";
+}
+/**
+* Generate a time-sortable unique run id, e.g.
+* `20260613T012345678Z-1a2b3c4d`. The timestamp prefix keeps S3 listings
+* and `cdkd events` output chronologically meaningful; the random suffix
+* guarantees uniqueness across concurrent runs.
+*/
+function newDeploymentRunId(now = /* @__PURE__ */ new Date()) {
+	return `${now.toISOString().replace(/[-:.]/g, "")}-${randomUUID().slice(0, 8)}`;
+}
+/** S3 key of a run's JSONL event stream. */
+function deploymentEventsKey(prefix, stackName, region, runId) {
+	return `${prefix}/${stackName}/${region}/deployments/${runId}.jsonl`;
+}
+/** S3 key of a stack's run index. */
+function deploymentEventsIndexKey(prefix, stackName, region) {
+	return `${prefix}/${stackName}/${region}/deployments/index.json`;
+}
+/**
+* Buffering JSONL writer for one deployment run. Implements the
+* {@link DeploymentEventRecorder} seam the deploy engine / destroy
+* runner emit through.
+*/
+var DeploymentEventsStore = class {
+	logger = getLogger().child("DeploymentEvents");
+	backend;
+	stackName;
+	region;
+	command;
+	runId;
+	cdkdVersion;
+	startedAt;
+	/** All events recorded so far (the full JSONL body is re-PUT per flush —
+	* S3 has no append, and metadata-only events are small). */
+	events = [];
+	/** Number of events already persisted by the last successful flush. */
+	persistedCount = 0;
+	flushTimer;
+	/** Serializes S3 writes so flushes never interleave. */
+	writeChain = Promise.resolve();
+	warnedOnce = false;
+	finalized = false;
+	constructor(backend, options) {
+		this.backend = backend;
+		this.stackName = options.stackName;
+		this.region = options.region;
+		this.command = options.command;
+		this.runId = options.runId ?? newDeploymentRunId();
+		this.cdkdVersion = options.cdkdVersion ?? getCdkdVersion();
+		this.startedAt = (/* @__PURE__ */ new Date()).toISOString();
+	}
+	/**
+	* Buffer one event (synchronous, never throws). The timestamp is
+	* stamped here so emitters don't need to.
+	*/
+	record(event) {
+		try {
+			if (this.finalized) return;
+			this.events.push({
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				...event
+			});
+			if (this.events.length - this.persistedCount >= FLUSH_EVENT_THRESHOLD) this.scheduleFlush(0);
+			else this.scheduleFlush(FLUSH_INTERVAL_MS);
+		} catch {}
+	}
+	/**
+	* Final flush + index update. Called by the owner (deploy CLI per-stack
+	* finally / destroy runner finally) after the run reaches a terminal
+	* state. Best-effort: never throws.
+	*/
+	async finalize(result) {
+		if (this.finalized) return;
+		this.finalized = true;
+		if (this.flushTimer) {
+			clearTimeout(this.flushTimer);
+			this.flushTimer = void 0;
+		}
+		if (this.events.length === 0) return;
+		await this.enqueueWrite(async () => {
+			await this.doFlush();
+			await this.updateIndex(result);
+		});
+	}
+	/** Await any in-flight async flushes (used by tests). */
+	async drain() {
+		await this.writeChain;
+	}
+	scheduleFlush(delayMs) {
+		if (this.flushTimer) {
+			if (delayMs > 0) return;
+			clearTimeout(this.flushTimer);
+		}
+		this.flushTimer = setTimeout(() => {
+			this.flushTimer = void 0;
+			this.enqueueWrite(() => this.doFlush());
+		}, delayMs);
+		this.flushTimer.unref?.();
+	}
+	enqueueWrite(op) {
+		const next = this.writeChain.then(op).catch((err) => {
+			this.warnOnce(`Failed to persist deployment events for run ${this.runId}: ${err instanceof Error ? err.message : String(err)}`);
+		});
+		this.writeChain = next;
+		return next;
+	}
+	async doFlush() {
+		if (this.events.length === 0 || this.events.length === this.persistedCount) return;
+		const snapshotCount = this.events.length;
+		const body = this.events.slice(0, snapshotCount).map((e) => JSON.stringify(e)).join("\n");
+		await this.backend.putRawObject(deploymentEventsKey(this.backend.prefix, this.stackName, this.region, this.runId), body + "\n", "application/x-ndjson");
+		this.persistedCount = snapshotCount;
+	}
+	/**
+	* Prepend this run's summary to `deployments/index.json`, truncated to
+	* the last {@link DEPLOYMENT_EVENTS_MAX_INDEX_RUNS} runs. Read-modify-
+	* write WITHOUT optimistic locking — last-writer-wins (documented
+	* trade-off; the per-run `.jsonl` files are the source of truth).
+	*/
+	async updateIndex(result) {
+		const key = deploymentEventsIndexKey(this.backend.prefix, this.stackName, this.region);
+		let existingRuns = [];
+		try {
+			const raw = await this.backend.getRawObject(key);
+			if (raw !== null) {
+				const parsed = JSON.parse(raw);
+				if (Array.isArray(parsed.runs)) existingRuns = parsed.runs;
+			}
+		} catch (err) {
+			this.logger.debug(`Deployment-events index unreadable, rewriting: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		const runs = [{
+			runId: this.runId,
+			command: this.command,
+			cdkdVersion: this.cdkdVersion,
+			startedAt: this.startedAt,
+			finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			result,
+			eventCount: this.persistedCount
+		}, ...existingRuns.filter((r) => r.runId !== this.runId)].slice(0, 20);
+		const file = {
+			indexVersion: 1,
+			stackName: this.stackName,
+			region: this.region,
+			runs,
+			lastModified: Date.now()
+		};
+		await this.backend.putRawObject(key, JSON.stringify(file, null, 2));
+	}
+	warnOnce(message) {
+		if (this.warnedOnce) {
+			this.logger.debug(message);
+			return;
+		}
+		this.warnedOnce = true;
+		this.logger.warn(`${message} — continuing; deployment events are best-effort and never block the run.`);
+	}
+};
+/**
+* Read side for `cdkd events`: discovers regions / runs / event streams
+* under `{prefix}/{stackName}/{region}/deployments/`. Region discovery
+* deliberately does NOT rely on state.json — event files survive
+* `cdkd destroy`, so a destroyed stack's runs stay readable.
+*/
+var DeploymentEventsReader = class {
+	backend;
+	constructor(backend) {
+		this.backend = backend;
+	}
+	/**
+	* Regions that have a `deployments/` index or event stream for the
+	* stack. Derived from the raw key listing under `{prefix}/{stackName}/`.
+	*/
+	async listRegions(stackName) {
+		const prefix = `${this.backend.prefix}/${stackName}/`;
+		const keys = await this.backend.listRawKeys(prefix);
+		const regions = /* @__PURE__ */ new Set();
+		for (const key of keys) {
+			const segments = key.slice(prefix.length).split("/");
+			if (segments.length === 3 && segments[1] === "deployments" && segments[0]) regions.add(segments[0]);
+		}
+		return [...regions].sort();
+	}
+	/**
+	* Run summaries for `(stackName, region)`, newest first. Returns the
+	* index file's `runs` (already newest-first); when the index is missing
+	* or unreadable, falls back to enumerating `{runId}.jsonl` keys (sorted
+	* descending — runIds are time-prefixed).
+	*
+	* In the fallback path the run's terminal result / command / version are
+	* NOT known from the key alone, so each run's JSONL is read and its last
+	* `RUN_FINISHED` (+ first `RUN_STARTED`) event mined for the true result,
+	* command, version, and timestamps. A run whose JSONL has no terminal
+	* `RUN_FINISHED` (interrupted run, or one whose index write lost the
+	* race) is reported as `'UNKNOWN'` — it is NEVER fabricated as `'FAILED'`,
+	* which would mislabel a successful run that merely failed to update the
+	* derived index.
+	*/
+	async listRuns(stackName, region) {
+		const key = deploymentEventsIndexKey(this.backend.prefix, stackName, region);
+		try {
+			const raw = await this.backend.getRawObject(key);
+			if (raw !== null) {
+				const parsed = JSON.parse(raw);
+				if (Array.isArray(parsed.runs)) return parsed.runs;
+			}
+		} catch {}
+		const dirPrefix = `${this.backend.prefix}/${stackName}/${region}/deployments/`;
+		const runIds = (await this.backend.listRawKeys(dirPrefix)).filter((k) => k.endsWith(".jsonl")).map((k) => k.slice(dirPrefix.length, -6)).sort().reverse();
+		return Promise.all(runIds.map((runId) => this.summarizeRunFromJsonl(stackName, region, runId)));
+	}
+	/**
+	* Reconstruct a {@link DeploymentRunSummary} for the index-fallback path
+	* by reading the run's JSONL. Derives the true result from the last
+	* `RUN_FINISHED` event; absent that, returns `'UNKNOWN'` rather than
+	* fabricating a definitive failure.
+	*/
+	async summarizeRunFromJsonl(stackName, region, runId) {
+		const fallback = {
+			runId,
+			command: "deploy",
+			cdkdVersion: "unknown",
+			startedAt: "",
+			finishedAt: "",
+			result: "UNKNOWN",
+			eventCount: 0
+		};
+		let events = null;
+		try {
+			events = await this.readRunEvents(stackName, region, runId);
+		} catch {
+			return fallback;
+		}
+		if (events === null || events.length === 0) return fallback;
+		const started = events.find((e) => e.eventType === "RUN_STARTED");
+		let finished;
+		for (const e of events) if (e.eventType === "RUN_FINISHED") finished = e;
+		return {
+			runId,
+			command: started?.command ?? fallback.command,
+			cdkdVersion: started?.cdkdVersion ?? fallback.cdkdVersion,
+			startedAt: started?.timestamp ?? fallback.startedAt,
+			finishedAt: finished?.timestamp ?? fallback.finishedAt,
+			result: finished?.result ?? "UNKNOWN",
+			eventCount: events.length
+		};
+	}
+	/**
+	* Parse one run's JSONL event stream. Returns `null` when the run file
+	* does not exist. Malformed lines are skipped (a torn final line from
+	* an interrupted flush must not hide the rest of the stream).
+	*/
+	async readRunEvents(stackName, region, runId) {
+		const key = deploymentEventsKey(this.backend.prefix, stackName, region, runId);
+		const raw = await this.backend.getRawObject(key);
+		if (raw === null) return null;
+		const events = [];
+		for (const line of raw.split("\n")) {
+			const trimmed = line.trim();
+			if (!trimmed) continue;
+			try {
+				events.push(JSON.parse(trimmed));
+			} catch {}
+		}
+		return events;
+	}
+};
+
+//#endregion
+//#region src/cli/commands/deployment-events-run.ts
+/**
+* Run-level deployment-event bracket helpers (issue #808).
+*
+* The per-resource + rollback events are emitted by `DeployEngine` /
+* `destroy-runner.ts`; the RUN-level events (`RUN_STARTED` /
+* `RUN_FINISHED`) and the recorder lifecycle (`finalize()` in a `finally`)
+* are owned by the `cdkd deploy` / `cdkd destroy` CLIs. That run-level
+* bracket was originally inline in `deploy.ts` / `destroy.ts` and could
+* only be exercised through the full synth → STS → work-graph pipeline.
+*
+* These thin helpers extract the bracket so it is directly unit-testable
+* (and shared between the two commands), with the exact contract:
+*
+*   - **`--dry-run` creates NO recorder** (no events at all for a dry run).
+*   - `RUN_STARTED` is emitted the moment the recorder is created.
+*   - A successful run emits `RUN_FINISHED { result: 'SUCCEEDED', counts }`.
+*   - A failed run emits `RUN_FINISHED { result: 'FAILED', error }` via
+*     {@link extractDeploymentEventError} (error metadata only — no props).
+*   - `finalize(result)` is always called (caller's `finally`).
+*
+* All of this is best-effort: the recorder's `record()` / `finalize()`
+* never throw, so these helpers never need their own try/catch.
+*/
+/**
+* Create a {@link DeploymentEventsStore} and immediately emit its
+* `RUN_STARTED` event. Returns `undefined` under `--dry-run` (no recorder,
+* no events). The caller wires the returned recorder into the engine /
+* runner and `finalize()`s it in a `finally`.
+*/
+function startRunRecorder(args) {
+	if (args.dryRun) return void 0;
+	const recorder = new DeploymentEventsStore(args.backend, {
+		stackName: args.stackName,
+		region: args.region,
+		command: args.command,
+		...args.runId !== void 0 && { runId: args.runId },
+		...args.cdkdVersion !== void 0 && { cdkdVersion: args.cdkdVersion }
+	});
+	recorder.record({
+		eventType: "RUN_STARTED",
+		stackName: args.stackName,
+		command: args.command,
+		region: args.region,
+		cdkdVersion: recorder.cdkdVersion
+	});
+	return recorder;
+}
+/**
+* Emit a success `RUN_FINISHED`. No-op when `recorder` is `undefined`
+* (dry-run / older state). `durationMs` is optional (destroy does not
+* carry one at the run level).
+*/
+function recordRunSucceeded(recorder, stackName, counts, durationMs) {
+	recorder?.record({
+		eventType: "RUN_FINISHED",
+		stackName,
+		result: "SUCCEEDED",
+		...durationMs !== void 0 && { durationMs },
+		counts
+	});
+}
+/**
+* Emit a failure `RUN_FINISHED` carrying the extracted error metadata.
+* No-op when `recorder` is `undefined`.
+*/
+function recordRunFailed(recorder, stackName, error) {
+	recorder?.record({
+		eventType: "RUN_FINISHED",
+		stackName,
+		result: "FAILED",
+		error: extractDeploymentEventError(error)
+	});
+}
+
 //#endregion
 //#region src/state/export-index-store.ts
 /**
@@ -33932,10 +34313,27 @@ async function runDestroyForStack(stackName, state, ctx) {
 				if (shouldRetainResource(resource.deletionPolicy)) {
 					logger.info(`  ⊘ ${logicalId} (${resource.resourceType}) retained — DeletionPolicy: ${resource.deletionPolicy}`);
 					result.retainedCount++;
+					ctx.eventRecorder?.record({
+						eventType: "RESOURCE_RETAINED",
+						stackName,
+						operation: "DELETE",
+						logicalId,
+						resourceType: resource.resourceType,
+						...resource.provisionedBy && { provisionedBy: resource.provisionedBy }
+					});
 					return;
 				}
 				const baseLabel = `Deleting ${logicalId} (${resource.resourceType})`;
 				renderer.addTask(logicalId, baseLabel);
+				const resourceStartedAt = Date.now();
+				ctx.eventRecorder?.record({
+					eventType: "RESOURCE_STARTED",
+					stackName,
+					operation: "DELETE",
+					logicalId,
+					resourceType: resource.resourceType,
+					...resource.provisionedBy && { provisionedBy: resource.provisionedBy }
+				});
 				try {
 					const provider = destroyProviderRegistry.getProviderFor({
 						resourceType: resource.resourceType,
@@ -33979,6 +34377,16 @@ async function runDestroyForStack(stackName, state, ctx) {
 					renderer.removeTask(logicalId);
 					logger.info(`  ${formatResourceLine("deleted", logicalId, resource.resourceType)}`);
 					result.deletedCount++;
+					ctx.eventRecorder?.record({
+						eventType: "RESOURCE_SUCCEEDED",
+						stackName,
+						operation: "DELETE",
+						logicalId,
+						resourceType: resource.resourceType,
+						...resource.provisionedBy && { provisionedBy: resource.provisionedBy },
+						...resource.physicalId && { physicalId: resource.physicalId },
+						durationMs: Date.now() - resourceStartedAt
+					});
 					delete remainingResources[logicalId];
 					persistStateAfterDelete(logicalId);
 				} catch (error) {
@@ -33987,15 +34395,45 @@ async function runDestroyForStack(stackName, state, ctx) {
 					if (msg.includes("does not exist") || msg.includes("not found") || msg.includes("No policy found") || msg.includes("NoSuchEntity") || msg.includes("NotFoundException")) {
 						logger.debug(`  ${logicalId} already deleted, removing from state`);
 						result.deletedCount++;
+						ctx.eventRecorder?.record({
+							eventType: "RESOURCE_SUCCEEDED",
+							stackName,
+							operation: "DELETE",
+							logicalId,
+							resourceType: resource.resourceType,
+							...resource.provisionedBy && { provisionedBy: resource.provisionedBy },
+							...resource.physicalId && { physicalId: resource.physicalId },
+							durationMs: Date.now() - resourceStartedAt
+						});
 						delete remainingResources[logicalId];
 						persistStateAfterDelete(logicalId);
 					} else if (error instanceof ResourceTimeoutError) {
 						const wrapped = new ProvisioningError(error.message, resource.resourceType, logicalId, resource.physicalId, error);
 						logger.error(`  ✗ Failed to delete ${logicalId}:`, wrapped.message);
 						result.errorCount++;
+						ctx.eventRecorder?.record({
+							eventType: "RESOURCE_FAILED",
+							stackName,
+							operation: "DELETE",
+							logicalId,
+							resourceType: resource.resourceType,
+							...resource.provisionedBy && { provisionedBy: resource.provisionedBy },
+							durationMs: Date.now() - resourceStartedAt,
+							error: extractDeploymentEventError(wrapped)
+						});
 					} else {
 						logger.error(`  ✗ Failed to delete ${logicalId}:`, String(error));
 						result.errorCount++;
+						ctx.eventRecorder?.record({
+							eventType: "RESOURCE_FAILED",
+							stackName,
+							operation: "DELETE",
+							logicalId,
+							resourceType: resource.resourceType,
+							...resource.provisionedBy && { provisionedBy: resource.provisionedBy },
+							durationMs: Date.now() - resourceStartedAt,
+							error: extractDeploymentEventError(error)
+						});
 					}
 				} finally {
 					renderer.removeTask(logicalId);
@@ -35097,6 +35535,14 @@ async function deployCommand(stacks, options) {
 			stackProviderRegistry.setCustomResourceResponseBucket(stateBucket, baseRegion);
 			if (options.allowUnsupportedTypes?.length) stackProviderRegistry.allowUnsupportedTypes(options.allowUnsupportedTypes);
 			if (options.allowUnsupportedProperties?.length) stackProviderRegistry.allowUnsupportedProperties(options.allowUnsupportedProperties);
+			const eventRecorder = startRunRecorder({
+				backend: stackStateBackend,
+				stackName: stackInfo.stackName,
+				region: stackRegion,
+				command: "deploy",
+				dryRun: options.dryRun
+			});
+			let runResult = "SUCCEEDED";
 			try {
 				if (skipPrefix) {
 					const existing = await stackStateBackend.getState(stackInfo.stackName, stackRegion);
@@ -35152,6 +35598,7 @@ async function deployCommand(stacks, options) {
 					concurrency: options.concurrency,
 					dryRun: options.dryRun,
 					noRollback: !options.rollback,
+					...eventRecorder && { eventRecorder },
 					...recreateViaCcApiTargets && recreateViaCcApiTargets.size > 0 && { recreateViaCcApiTargets },
 					...recreateViaSdkProviderTargets && recreateViaSdkProviderTargets.size > 0 && { recreateViaSdkProviderTargets },
 					captureObservedState: resolveCaptureObservedState(options.captureObservedState),
@@ -35189,7 +35636,17 @@ async function deployCommand(stacks, options) {
 				}
 				if (options.dryRun) logger.info(`\n${green("✓")} ${bold("Dry run completed")} - no actual changes made`);
 				else logger.info(`\n${green("✓")} ${bold("Deployment completed successfully")}`);
+				recordRunSucceeded(eventRecorder, stackInfo.stackName, {
+					created: deployResult.created,
+					updated: deployResult.updated,
+					deleted: deployResult.deleted
+				}, deployResult.durationMs);
+			} catch (deployError) {
+				runResult = "FAILED";
+				recordRunFailed(eventRecorder, stackInfo.stackName, deployError);
+				throw deployError;
 			} finally {
+				if (eventRecorder) await eventRecorder.finalize(runResult);
 				stackAwsClients.destroy();
 				stateS3Client.destroy();
 				switchRegion(baseRegion);
@@ -37691,42 +38148,70 @@ async function destroyCommand(stackArgs, options) {
 				totalErrors++;
 				continue;
 			}
-			const result = await withNestedStackContext({
-				stateBackend,
-				lockManager,
-				providerRegistry,
-				parentStackName: stackName,
-				parentRegion: stackTargetRegion,
-				accountId,
-				awsClients,
-				stateBucket,
-				exportIndexStore,
-				destroyOptions: {
+			const eventRecorder = startRunRecorder({
+				backend: stateBackend,
+				stackName,
+				region: stackTargetRegion,
+				command: "destroy"
+			});
+			let destroyRunResult = "SUCCEEDED";
+			try {
+				const result = await withNestedStackContext({
+					stateBackend,
+					lockManager,
+					providerRegistry,
+					parentStackName: stackName,
+					parentRegion: stackTargetRegion,
+					accountId,
+					awsClients,
+					stateBucket,
+					exportIndexStore,
+					destroyOptions: {
+						...options.profile && { profile: options.profile },
+						...options.removeProtection === true && { removeProtection: true },
+						...options.resourceWarnAfter?.globalMs !== void 0 && { resourceWarnAfterMs: options.resourceWarnAfter.globalMs },
+						...options.resourceTimeout?.globalMs !== void 0 && { resourceTimeoutMs: options.resourceTimeout.globalMs },
+						...options.resourceWarnAfter?.perTypeMs && { resourceWarnAfterByType: options.resourceWarnAfter.perTypeMs },
+						...options.resourceTimeout?.perTypeMs && { resourceTimeoutByType: options.resourceTimeout.perTypeMs }
+					}
+				}, () => runDestroyForStack(stackName, stateResult.state, {
+					stateBackend,
+					lockManager,
+					providerRegistry,
+					baseAwsClients: awsClients,
+					baseRegion: region,
 					...options.profile && { profile: options.profile },
-					...options.removeProtection === true && { removeProtection: true },
+					stateBucket,
+					skipConfirmation: options.yes || options.force,
+					removeProtection: options.removeProtection === true,
+					exportIndexStore,
+					...options.allowUnsupportedTypes?.length && { allowUnsupportedTypes: options.allowUnsupportedTypes },
 					...options.resourceWarnAfter?.globalMs !== void 0 && { resourceWarnAfterMs: options.resourceWarnAfter.globalMs },
 					...options.resourceTimeout?.globalMs !== void 0 && { resourceTimeoutMs: options.resourceTimeout.globalMs },
 					...options.resourceWarnAfter?.perTypeMs && { resourceWarnAfterByType: options.resourceWarnAfter.perTypeMs },
-					...options.resourceTimeout?.perTypeMs && { resourceTimeoutByType: options.resourceTimeout.perTypeMs }
-				}
-			}, () => runDestroyForStack(stackName, stateResult.state, {
-				stateBackend,
-				lockManager,
-				providerRegistry,
-				baseAwsClients: awsClients,
-				baseRegion: region,
-				...options.profile && { profile: options.profile },
-				stateBucket,
-				skipConfirmation: options.yes || options.force,
-				removeProtection: options.removeProtection === true,
-				exportIndexStore,
-				...options.allowUnsupportedTypes?.length && { allowUnsupportedTypes: options.allowUnsupportedTypes },
-				...options.resourceWarnAfter?.globalMs !== void 0 && { resourceWarnAfterMs: options.resourceWarnAfter.globalMs },
-				...options.resourceTimeout?.globalMs !== void 0 && { resourceTimeoutMs: options.resourceTimeout.globalMs },
-				...options.resourceWarnAfter?.perTypeMs && { resourceWarnAfterByType: options.resourceWarnAfter.perTypeMs },
-				...options.resourceTimeout?.perTypeMs && { resourceTimeoutByType: options.resourceTimeout.perTypeMs }
-			}));
-			totalErrors += result.errorCount;
+					...options.resourceTimeout?.perTypeMs && { resourceTimeoutByType: options.resourceTimeout.perTypeMs },
+					eventRecorder
+				}));
+				totalErrors += result.errorCount;
+				destroyRunResult = result.errorCount > 0 ? "FAILED" : "SUCCEEDED";
+				eventRecorder.record({
+					eventType: "RUN_FINISHED",
+					stackName,
+					result: destroyRunResult,
+					counts: {
+						created: 0,
+						updated: 0,
+						deleted: result.deletedCount,
+						...result.errorCount > 0 && { failed: result.errorCount }
+					}
+				});
+			} catch (destroyError) {
+				destroyRunResult = "FAILED";
+				recordRunFailed(eventRecorder, stackName, destroyError);
+				throw destroyError;
+			} finally {
+				await eventRecorder.finalize(destroyRunResult);
+			}
 		}
 		if (totalErrors > 0) throw new PartialFailureError(`Destroy completed with ${totalErrors} resource error(s). State preserved — inspect 'cdkd state show <stack>' and re-run 'cdkd destroy' to retry.`);
 	} finally {
@@ -37751,6 +38236,147 @@ function createDestroyCommand() {
 	return cmd;
 }
 
+//#endregion
+//#region src/cli/commands/events.ts
+/**
+* `cdkd events <stack>` — read back the structured deployment events
+* (issue #808) cdkd persists per deploy / destroy run, the local
+* equivalent of CloudFormation's `DescribeStackEvents`.
+*
+* Two modes:
+*   - No `--run`: list the recorded runs for the stack, newest first
+*     (runId, command, cdkd version, result, started/finished, event count).
+*   - `--run <id>`: print the full ordered event stream for that one run.
+*
+* `--format json` (alias `--json`) emits machine-readable JSON for tooling
+* / AI-agent hand-off. Events survive `cdkd destroy` (they live under a
+* separate `deployments/` key family from `state.json`), so a destroyed
+* stack's failure history stays readable.
+*/
+async function eventsCommand(stackName, options) {
+	const logger = getLogger();
+	if (options.verbose) logger.setLevel("debug");
+	warnIfDeprecatedRegion(options);
+	const asJson = options.json === true;
+	const awsClients = new AwsClients({
+		...options.region && { region: options.region },
+		...options.profile && { profile: options.profile }
+	});
+	setAwsClients(awsClients);
+	try {
+		const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+		const bucket = await resolveStateBucketWithDefault(options.stateBucket, region);
+		const prefix = options.statePrefix ?? "cdkd";
+		const stateBackend = new S3StateBackend(awsClients.s3, {
+			bucket,
+			prefix
+		}, {
+			region,
+			...options.profile && { profile: options.profile }
+		});
+		await stateBackend.verifyBucketExists();
+		const reader = new DeploymentEventsReader(stateBackend);
+		const targetRegion = await resolveEventsRegion(reader, stackName, options.stackRegion);
+		if (options.run) {
+			const events = await reader.readRunEvents(stackName, targetRegion, options.run);
+			if (events === null) throw new CdkdError(`No deployment-event stream found for run '${options.run}' of stack '${stackName}' in region '${targetRegion}'.`, "EVENTS_RUN_NOT_FOUND");
+			if (asJson) {
+				process.stdout.write(JSON.stringify(events, null, 2) + "\n");
+				return;
+			}
+			printRunEvents(stackName, targetRegion, options.run, events);
+			return;
+		}
+		const runs = await reader.listRuns(stackName, targetRegion);
+		if (asJson) {
+			process.stdout.write(JSON.stringify({
+				stackName,
+				region: targetRegion,
+				runs
+			}, null, 2) + "\n");
+			return;
+		}
+		printRunList(stackName, targetRegion, runs);
+	} finally {
+		awsClients.destroy();
+	}
+}
+/**
+* Pick the region whose `deployments/` key family holds this stack's run
+* history. When `--stack-region` is supplied it is honored verbatim;
+* otherwise the single discovered region is used, and an ambiguous (>1)
+* or missing (0) history surfaces an actionable error.
+*/
+async function resolveEventsRegion(reader, stackName, explicitRegion) {
+	if (explicitRegion) return explicitRegion;
+	const regions = await reader.listRegions(stackName);
+	if (regions.length === 0) throw new CdkdError(`No deployment-event history found for stack '${stackName}'. Events are recorded by 'cdkd deploy' / 'cdkd destroy' (issue #808); a stack deployed by an older cdkd version has none.`, "EVENTS_NOT_FOUND");
+	if (regions.length > 1) throw new CdkdError(`Stack '${stackName}' has deployment-event history in multiple regions: ${regions.join(", ")}. Re-run with '--stack-region <region>' to disambiguate.`, "EVENTS_REGION_AMBIGUOUS");
+	return regions[0];
+}
+/** Human-readable run listing (newest first). */
+function printRunList(stackName, region, runs) {
+	const logger = getLogger();
+	logger.info(`${bold("Deployment runs for")} ${cyan(stackName)} ${gray(`(${region})`)}`);
+	if (runs.length === 0) {
+		logger.info(gray("  (no runs recorded)"));
+		return;
+	}
+	for (const run of runs) {
+		const resultColored = run.result === "SUCCEEDED" ? green(run.result) : run.result === "UNKNOWN" ? gray(run.result) : red(run.result);
+		logger.info(`  ${cyan(run.runId)}  ${run.command}  ${resultColored}  ${gray(run.startedAt || "?")} -> ${gray(run.finishedAt || "?")}  ${gray(`cdkd ${run.cdkdVersion}`)}  ${gray(`${run.eventCount} events`)}`);
+	}
+	logger.info(gray(`\nUse 'cdkd events ${stackName} --run <runId>' to read one run's events.`));
+}
+/** Human-readable single-run event stream (in recorded order). */
+function printRunEvents(stackName, region, runId, events) {
+	const logger = getLogger();
+	logger.info(`${bold("Events for run")} ${cyan(runId)} ${gray(`(${stackName}, ${region})`)}`);
+	if (events.length === 0) {
+		logger.info(gray("  (no events)"));
+		return;
+	}
+	for (const e of events) {
+		const parts = [gray(e.timestamp), colorizeEventType(e.eventType)];
+		if (e.logicalId) parts.push(`${e.logicalId}${e.resourceType ? ` (${e.resourceType})` : ""}`);
+		if (e.operation) parts.push(gray(e.operation));
+		if (e.provisionedBy) parts.push(gray(`[${e.provisionedBy}]`));
+		if (e.command) parts.push(gray(e.command));
+		if (e.region) parts.push(gray(e.region));
+		if (e.cdkdVersion) parts.push(gray(`cdkd ${e.cdkdVersion}`));
+		if (e.result) parts.push(e.result === "SUCCEEDED" ? green(e.result) : red(e.result));
+		if (typeof e.durationMs === "number") parts.push(gray(`${e.durationMs}ms`));
+		if (e.counts) parts.push(gray(`+${e.counts.created}/~${e.counts.updated}/-${e.counts.deleted}` + (e.counts.failed ? ` !${e.counts.failed}` : "")));
+		logger.info(`  ${parts.join("  ")}`);
+		if (e.error) {
+			const code = e.error.awsErrorCode ? ` (${e.error.awsErrorCode})` : "";
+			const reqId = e.error.requestId ? gray(` requestId=${e.error.requestId}`) : "";
+			logger.info(`      ${red(`${e.error.name}${code}: ${e.error.message}`)}${reqId}`);
+		}
+	}
+}
+/** Color the event-type token by its lifecycle phase. */
+function colorizeEventType(eventType) {
+	if (eventType.endsWith("FAILED")) return red(eventType);
+	if (eventType.endsWith("SUCCEEDED") || eventType === "RUN_FINISHED") return green(eventType);
+	if (eventType.startsWith("ROLLBACK")) return yellow(eventType);
+	return cyan(eventType);
+}
+/**
+* Create the `cdkd events` command.
+*/
+function createEventsCommand() {
+	const cmd = new Command("events").description("Read back structured deployment events (cdkd's DescribeStackEvents equivalent, issue #808)").argument("<stack>", "Stack name (physical CloudFormation name)").option("--run <runId>", "Read a single run's full event stream instead of the run listing").option("--stack-region <region>", "Disambiguate a stack with event history in multiple regions").option("--json", "Output as JSON", false).option("--format <format>", "Output format ('json' is equivalent to --json)").action(withErrorHandling((stack, options) => {
+		return eventsCommand(stack, {
+			...options,
+			json: options.json === true || options.format === "json"
+		});
+	}));
+	[...commonOptions, ...stateOptions].forEach((opt) => cmd.addOption(opt));
+	cmd.addOption(deprecatedRegionOption);
+	return cmd;
+}
+
 //#endregion
 //#region src/cli/cdk-path.ts
 /**
@@ -52914,7 +53540,7 @@ function reorderArgs(argv) {
 async function main() {
 	installPipeCloseHandler();
 	const program = new Command();
-	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.219.9");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.220.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());
@@ -52922,6 +53548,7 @@ async function main() {
 	program.addCommand(createDiffCommand());
 	program.addCommand(createDriftCommand());
 	program.addCommand(createDestroyCommand());
+	program.addCommand(createEventsCommand());
 	program.addCommand(createOrphanCommand());
 	program.addCommand(createImportCommand());
 	program.addCommand(createPublishAssetsCommand());