@keystrokehq/cli 0.0.31 → 0.0.37

package/dist/{orgs.create.handler-BO70zIdp.mjs → orgs.create.handler-BKvSmkU3.mjs}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
-import { a as ui } from "./keystroke.mjs";
-import { i as writeJson } from "./output-BWcVRt-T.mjs";
-import { i as requireClient } from "./context-sgKhRc5v.mjs";
-import { n as isIamJsonMode, t as handleIamError } from "./iam-command-utils-CSZj4XlH.mjs";
+import { p as ui } from "./keystroke.mjs";
+import { i as writeJson } from "./output-DnIFEmi5.mjs";
+import { i as requireClient } from "./context-ebZssGCY.mjs";
+import { n as isIamJsonMode, t as handleIamError } from "./iam-command-utils-DNDN0wT6.mjs";
 //#region src/commands/admin/orgs.create.handler.ts
 async function handleAdminOrgsCreate(options, ctx) {
 	const client = requireClient(ctx);

package/dist/{orgs.get.handler-BuGg5bc9.mjs → orgs.get.handler-BA-CexIY.mjs}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
-import { a as ui } from "./keystroke.mjs";
-import { i as writeJson } from "./output-BWcVRt-T.mjs";
-import { i as requireClient } from "./context-sgKhRc5v.mjs";
-import { n as isIamJsonMode, t as handleIamError } from "./iam-command-utils-CSZj4XlH.mjs";
+import { p as ui } from "./keystroke.mjs";
+import { i as writeJson } from "./output-DnIFEmi5.mjs";
+import { i as requireClient } from "./context-ebZssGCY.mjs";
+import { n as isIamJsonMode, t as handleIamError } from "./iam-command-utils-DNDN0wT6.mjs";
 //#region src/commands/admin/orgs.get.handler.ts
 async function handleAdminOrgsGet(options, ctx) {
 	const client = requireClient(ctx);

package/dist/{orgs.list.handler--5HutMkl.mjs → orgs.list.handler-eCEg5kC1.mjs}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
-import { a as ui } from "./keystroke.mjs";
-import { i as writeJson } from "./output-BWcVRt-T.mjs";
-import { i as requireClient } from "./context-sgKhRc5v.mjs";
-import { n as isIamJsonMode, t as handleIamError } from "./iam-command-utils-CSZj4XlH.mjs";
+import { p as ui } from "./keystroke.mjs";
+import { i as writeJson } from "./output-DnIFEmi5.mjs";
+import { i as requireClient } from "./context-ebZssGCY.mjs";
+import { n as isIamJsonMode, t as handleIamError } from "./iam-command-utils-DNDN0wT6.mjs";
 import Table from "cli-table3";
 //#region src/commands/admin/orgs.list.handler.ts
 async function handleAdminOrgsList(_options, ctx) {

package/dist/{output-BWcVRt-T.mjs → output-DnIFEmi5.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { j as throwReportedCliExit } from "./keystroke.mjs";
+import { N as throwReportedCliExit } from "./keystroke.mjs";
 import { z } from "zod";
 //#region src/lib/output.ts
 /**

package/dist/package-manager-BP3-q8hh.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+
+import { x as toErrorMessage } from "./keystroke.mjs";
+import { dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+//#region src/lib/package-manager.ts
+const PackageManagerValues = [
+	"npm",
+	"pnpm",
+	"yarn",
+	"bun"
+];
+function parsePackageManagerField(value) {
+	if (typeof value !== "string" || value.length === 0) return null;
+	const name = value.split("@")[0]?.trim();
+	if (name && PackageManagerValues.includes(name)) return name;
+	return null;
+}
+function detectFromLockfiles(directory) {
+	if (existsSync(join(directory, "bun.lockb")) || existsSync(join(directory, "bun.lock"))) return "bun";
+	if (existsSync(join(directory, "pnpm-lock.yaml"))) return "pnpm";
+	if (existsSync(join(directory, "yarn.lock"))) return "yarn";
+	if (existsSync(join(directory, "package-lock.json")) || existsSync(join(directory, "npm-shrinkwrap.json"))) return "npm";
+	return null;
+}
+function readPackageManagerField(directory) {
+	const packageJsonPath = join(directory, "package.json");
+	if (!existsSync(packageJsonPath)) return null;
+	try {
+		return parsePackageManagerField(JSON.parse(readFileSync(packageJsonPath, "utf8")).packageManager);
+	} catch {
+		return null;
+	}
+}
+function walkProjectDirectories(startDir) {
+	const directories = [];
+	let directory = startDir;
+	while (true) {
+		directories.push(directory);
+		const parent = dirname(directory);
+		if (parent === directory) break;
+		directory = parent;
+	}
+	return directories;
+}
+function hasPackageManagerSignal(cwd) {
+	for (const directory of walkProjectDirectories(cwd)) {
+		if (detectFromLockfiles(directory)) return true;
+		if (readPackageManagerField(directory)) return true;
+	}
+	return false;
+}
+/**
+* Infers the package manager for the current working directory by walking up
+* from `cwd` and preferring lockfiles (monorepo roots) over nested package.json
+* files without lockfiles.
+*/
+function detectPackageManager(options = {}) {
+	let packageManagerFromField = null;
+	for (const directory of walkProjectDirectories(options.cwd ?? process.cwd())) {
+		const fromLockfiles = detectFromLockfiles(directory);
+		if (fromLockfiles) return fromLockfiles;
+		const fromField = readPackageManagerField(directory);
+		if (fromField && !packageManagerFromField) packageManagerFromField = fromField;
+	}
+	return packageManagerFromField ?? "npm";
+}
+async function resolvePackageManagerResolution(options = {}) {
+	const cwd = options.cwd ?? process.cwd();
+	if (hasPackageManagerSignal(cwd)) return {
+		packageManager: detectPackageManager({ cwd }),
+		source: "project"
+	};
+	if (await (options.isPackageManagerAvailable ?? isPackageManagerOnPath)("pnpm")) return {
+		packageManager: "pnpm",
+		source: "preferred"
+	};
+	return {
+		packageManager: "npm",
+		source: "fallback"
+	};
+}
+function formatPackageInstallCommand(packageName, options = {}) {
+	const packageManager = options.packageManager ?? detectPackageManager({ cwd: options.cwd });
+	if (packageManager === "npm") return `npm install ${packageName}`;
+	if (packageManager === "pnpm") return `pnpm add ${packageName}`;
+	if (packageManager === "yarn") return `yarn add ${packageName}`;
+	return `bun add ${packageName}`;
+}
+function buildProjectInstallCommand(packageManager) {
+	if (packageManager === "pnpm") return {
+		command: "pnpm",
+		args: ["install"]
+	};
+	if (packageManager === "yarn") return {
+		command: "yarn",
+		args: ["install"]
+	};
+	if (packageManager === "bun") return {
+		command: "bun",
+		args: ["install"]
+	};
+	return {
+		command: "npm",
+		args: ["install"]
+	};
+}
+function isPackageManagerOnPath(packageManager) {
+	return new Promise((resolve) => {
+		const child = spawn(packageManager, ["--version"], {
+			stdio: "ignore",
+			shell: process.platform === "win32"
+		});
+		child.on("error", () => resolve(false));
+		child.on("close", (code) => resolve(code === 0));
+	});
+}
+function readYarnMajorVersion() {
+	return new Promise((resolve) => {
+		const child = spawn("yarn", ["--version"], {
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			],
+			shell: process.platform === "win32"
+		});
+		let output = "";
+		child.stdout?.on("data", (chunk) => {
+			output += chunk.toString();
+		});
+		child.on("error", () => resolve(null));
+		child.on("close", (code) => {
+			if (code !== 0) {
+				resolve(null);
+				return;
+			}
+			const major = Number.parseInt(output.trim().split(".")[0] ?? "", 10);
+			resolve(Number.isFinite(major) ? major : null);
+		});
+	});
+}
+async function runProjectInstall(options) {
+	const installCommand = buildProjectInstallCommand(options.packageManager);
+	return (options.runCommand ?? runPackageManagerCommand)(installCommand, { cwd: options.cwd });
+}
+function runPackageManagerCommand({ command, args }, options) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			cwd: options.cwd,
+			stdio: "inherit",
+			shell: process.platform === "win32"
+		});
+		child.on("error", (error) => {
+			reject(new Error(`Failed to start ${command}: ${toErrorMessage(error)}`, { cause: error }));
+		});
+		child.on("close", (code) => resolve(code ?? 1));
+	});
+}
+//#endregion
+export { readYarnMajorVersion as a, formatPackageInstallCommand as i, buildProjectInstallCommand as n, resolvePackageManagerResolution as o, detectPackageManager as r, runProjectInstall as s, PackageManagerValues as t };

package/dist/{paused.handler-DHvxz-cC.mjs → paused.handler-4wKMTKZ-.mjs}

@@ -1,18 +1,20 @@
 #!/usr/bin/env node
 
-import { a as ui, j as throwReportedCliExit, y as toErrorMessage } from "./keystroke.mjs";
-import { i as writeJson } from "./output-BWcVRt-T.mjs";
-import { i as requireClient } from "./context-sgKhRc5v.mjs";
+import { N as throwReportedCliExit, k as CliExitError, p as ui, x as toErrorMessage } from "./keystroke.mjs";
+import { i as writeJson } from "./output-DnIFEmi5.mjs";
+import { i as requireClient } from "./context-ebZssGCY.mjs";
+import { n as resolveWorkflowsDir } from "./resolve-project-DLKlAy0z.mjs";
+import { n as assertAuthoredWorkflowId, t as WORKFLOW_ID_COMMANDS } from "./authored-workflow-ref-fkHEEVnd.mjs";
 //#region src/commands/workflows/paused/paused.handler.ts
 async function handleWorkflowsPaused(options, ctx) {
 	const client = requireClient(ctx);
 	try {
-		const match = await listPausedRuns(client, options);
+		const result = await listPausedRuns(client, options);
 		if (ctx.jsonMode) {
-			writeJson(match.result);
+			writeJson(result);
 			return;
 		}
-		if (match.result.runs.length === 0) {
+		if (result.runs.length === 0) {
 			if (options.workflow) {
 				ui.hint(`No paused runs found for workflow "${options.workflow}".`);
 				return;
@@ -20,45 +22,30 @@ async function handleWorkflowsPaused(options, ctx) {
 			ui.hint("No paused workflow runs found.");
 			return;
 		}
-		if (options.workflow) {
-			if (match.kind === "authoredId") ui.hint(`Showing paused runs matching workflow id "${options.workflow}".`);
-			else if (match.kind === "name") ui.hint(`Showing paused runs matching workflow name "${options.workflow}".`);
-		}
-		for (const [index, run] of match.result.runs.entries()) {
+		if (options.workflow) ui.hint(`Showing paused runs matching workflow id "${options.workflow}".`);
+		for (const [index, run] of result.runs.entries()) {
 			ui.text(renderPausedRun(run));
-			if (index < match.result.runs.length - 1) ui.br();
+			if (index < result.runs.length - 1) ui.br();
 		}
-		ui.hint(`Showing ${match.result.runs.length} paused run(s)${options.type ? ` filtered to ${options.type}` : ""}.`);
+		ui.hint(`Showing ${result.runs.length} paused run(s)${options.type ? ` filtered to ${options.type}` : ""}.`);
 	} catch (error) {
+		if (error instanceof CliExitError && error.reported) throw error;
 		ui.error(`Failed to list paused workflow runs: ${toErrorMessage(error)}`);
 		throwReportedCliExit(`Failed to list paused workflow runs: ${toErrorMessage(error)}`, { cause: error });
 	}
 }
 async function listPausedRuns(client, options) {
-	if (!options.workflow) return {
-		kind: "all",
-		result: await client.runs.listPausedRuns({
-			type: options.type,
-			limit: options.limit
-		})
-	};
-	const byAuthoredId = await client.runs.listPausedRuns({
+	if (!options.workflow) return client.runs.listPausedRuns({
+		type: options.type,
+		limit: options.limit
+	});
+	const workflowsDir = await resolveWorkflowsDir(void 0);
+	if (workflowsDir) await assertAuthoredWorkflowId(options.workflow, workflowsDir, WORKFLOW_ID_COMMANDS.paused);
+	return client.runs.listPausedRuns({
 		authoredWorkflowId: options.workflow,
 		type: options.type,
 		limit: options.limit
 	});
-	if (byAuthoredId.runs.length > 0) return {
-		kind: "authoredId",
-		result: byAuthoredId
-	};
-	return {
-		kind: "name",
-		result: await client.runs.listPausedRuns({
-			workflowName: options.workflow,
-			type: options.type,
-			limit: options.limit
-		})
-	};
 }
 function renderPausedRun(run) {
 	const lines = [

package/dist/{projects-C5GZ5Jrf.mjs → projects-Wu_2fB_x.mjs}

@@ -1,28 +1,30 @@
 #!/usr/bin/env node
 
-import { n as JsonOptionSchema, t as JSON_OPTION_CONFIG } from "./output-BWcVRt-T.mjs";
-import { t as createTypedCommand } from "./commander-BlrSdFcu.mjs";
+import { n as JsonOptionSchema, t as JSON_OPTION_CONFIG } from "./output-DnIFEmi5.mjs";
+import { t as createTypedCommand } from "./commander-C6SSTQJ2.mjs";
 import { z } from "zod";
 //#region src/commands/projects/projects.command.ts
+const loadProjectsListHandler = async () => (await import("./list2.handler-BIaIyrQf.mjs")).handleProjectsList;
+const PROJECTS_LIST_OPTIONS = {
+	schema: JsonOptionSchema,
+	optionsConfig: { ...JSON_OPTION_CONFIG },
+	loadHandler: loadProjectsListHandler
+};
 function createProjectsCommand() {
 	return createTypedCommand({
 		name: "projects",
 		description: "List tracked Keystroke projects",
-		schema: JsonOptionSchema,
-		optionsConfig: { ...JSON_OPTION_CONFIG },
-		loadHandler: async () => (await import("./list.handler-BEMj3FyH.mjs")).handleProjectsList,
+		...PROJECTS_LIST_OPTIONS,
 		subcommands: [createTypedCommand({
 			name: "list",
 			description: "List all tracked Keystroke projects",
-			schema: JsonOptionSchema,
-			optionsConfig: { ...JSON_OPTION_CONFIG },
-			loadHandler: async () => (await import("./list.handler-BEMj3FyH.mjs")).handleProjectsList
+			...PROJECTS_LIST_OPTIONS
 		}), createTypedCommand({
 			name: "clear-cache",
 			description: "Clear the stored projects cache (projects.json)",
 			schema: z.object({}),
 			optionsConfig: {},
-			loadHandler: async () => (await import("./clear-cache.handler-BP0K1-uN.mjs")).handleProjectsClearCache
+			loadHandler: async () => (await import("./clear-cache.handler-gJpwslkK.mjs")).handleProjectsClearCache
 		})]
 	});
 }

package/dist/{register.handler-CePNU3sP.mjs → register.handler-BvAkXCwE.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
-import { a as ui, j as throwReportedCliExit, p as AUTH_HINT, v as isNetworkError, y as toErrorMessage } from "./keystroke.mjs";
-import { i as writeJson } from "./output-BWcVRt-T.mjs";
+import { N as throwReportedCliExit, b as isNetworkError, h as AUTH_HINT, p as ui, x as toErrorMessage } from "./keystroke.mjs";
+import { i as writeJson } from "./output-DnIFEmi5.mjs";
 //#region src/commands/integrations/register.handler.ts
 function exitWithError(ctx, message, opts) {
 	if (ctx.jsonMode) {

package/dist/{render-credential-Bn15FEUC.mjs → render-credential-D-H1ECDt.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { a as ui } from "./keystroke.mjs";
+import { p as ui } from "./keystroke.mjs";
 //#region src/lib/render-credential.ts
 function renderCredential(c, { full = false } = {}) {
 	ui.br();

package/dist/{render-operation-Bc7Wu1sP.mjs → render-operation-VdEPhoII.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
-import { a as ui } from "./keystroke.mjs";
-import { n as formatPackageInstallCommand } from "./package-manager-DT1EhOkS.mjs";
+import { p as ui } from "./keystroke.mjs";
+import { i as formatPackageInstallCommand } from "./package-manager-BP3-q8hh.mjs";
 //#region src/lib/render-operation.ts
 function isFull(op) {
 	return "inputSchemaJson" in op;

package/dist/{requirements.handler-B5rqCjMu.mjs → requirements.handler-Bab4kBtw.mjs}

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 
-import { a as ui, c as getProcessEnv, n as style, t as ANSI } from "./keystroke.mjs";
-import { i as writeJson } from "./output-BWcVRt-T.mjs";
-import { a as readManifestsFromOutDir } from "./dist-CTEtWDW4.mjs";
-import { t as requireWorkflowsDir } from "./resolve-project-E9mrh_el.mjs";
-import { t as readCredentialEnvMap } from "./credential-env-map-CRs0llf0.mjs";
-import { a as loadProjectDotenvFile, c as getTerminalContentWidth, o as manifestGroupKey, s as normalizeManifestScopeToServer, t as buildCredentialWorkflowConsumersByGroup, u as truncateWithEllipsis } from "./list-enrichment-DP1wEyBZ.mjs";
-import { t as groupCredentialRequirements } from "./credentials-DKrSaaLw.mjs";
+import { c as getProcessEnv, n as style, p as ui, t as ANSI } from "./keystroke.mjs";
+import { i as writeJson } from "./output-DnIFEmi5.mjs";
+import { a as readManifestsFromOutDir } from "./dist-BmbFJq8U.mjs";
+import { t as requireWorkflowsDir } from "./resolve-project-DLKlAy0z.mjs";
+import { t as readCredentialEnvMap } from "./credential-env-map-5a41jLwM.mjs";
+import { a as loadProjectDotenvFile, c as getTerminalContentWidth, o as manifestGroupKey, s as normalizeManifestScopeToServer, t as buildCredentialWorkflowConsumersByGroup, u as truncateWithEllipsis } from "./list-enrichment-dqbkXJzy.mjs";
+import { t as groupCredentialRequirements } from "./credentials-DtwLbee6.mjs";
 //#region src/commands/credentials/requirements/requirements-display.ts
 function dimLabel(label, width = 10) {
 	return style(label.padEnd(width), ANSI.dim);

package/dist/{resolve-cli-credentials-CAOSVMJP.mjs → resolve-cli-credentials-GVOOedoQ.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { n as credentials } from "./dist-Dw7gCE7y.mjs";
+import { n as credentials } from "./dist-B5jy238v.mjs";
 //#region src/lib/resolve-cli-credentials.ts
 /**
 * Resolves CLI credential inputs using explicit overrides first, then stored

package/dist/{resolve-project-E9mrh_el.mjs → resolve-project-DLKlAy0z.mjs}

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
-import { a as ui, k as ProjectNotFoundError } from "./keystroke.mjs";
-import { i as projects } from "./dist-Dw7gCE7y.mjs";
-import { n as findProjectRoot } from "./project-config-DudGRFPO.mjs";
+import { j as ProjectNotFoundError, p as ui } from "./keystroke.mjs";
+import { i as projects } from "./dist-B5jy238v.mjs";
+import { n as findProjectRoot, r as getProjectConfigPath } from "./project-config-DudGRFPO.mjs";
 import path from "node:path";
+import { access } from "node:fs/promises";
 //#region src/lib/resolve-project.ts
 /**
 * Resolve the project root from an explicit `--path` flag or by
@@ -19,17 +20,32 @@ async function resolveWorkflowsDir(explicitPath) {
 * Like `resolveWorkflowsDir` but throws a `ProjectNotFoundError`
 * when no project is found.
 */
-async function requireWorkflowsDir(explicitPath) {
-	const dir = await resolveWorkflowsDir(explicitPath);
-	if (dir) return dir;
-	ui.warn("No keystroke.config.ts found in this directory or any parent directory.");
+async function renderProjectNotFoundHints(fromCwd) {
+	if (fromCwd) ui.warn("No keystroke.config.ts found in this directory or any parent directory.");
+	else ui.warn("No keystroke.config.ts found at the provided project path.");
 	const lastProject = await projects.getLast();
 	if (lastProject) {
 		ui.hint(`Last used project: ${lastProject}`);
 		ui.hint(`  cd ${lastProject}`);
 	}
 	ui.hint("Run `keystroke init` to initialize a project, or use --path.");
-	throw new ProjectNotFoundError("No keystroke.config.ts found");
+}
+async function assertProjectConfigExists(projectRoot) {
+	try {
+		await access(getProjectConfigPath(projectRoot));
+	} catch {
+		await renderProjectNotFoundHints(false);
+		throw new ProjectNotFoundError("No keystroke.config.ts found");
+	}
+}
+async function requireWorkflowsDir(explicitPath) {
+	const dir = await resolveWorkflowsDir(explicitPath);
+	if (!dir) {
+		await renderProjectNotFoundHints(true);
+		throw new ProjectNotFoundError("No keystroke.config.ts found");
+	}
+	if (explicitPath) await assertProjectConfigExists(dir);
+	return dir;
 }
 //#endregion
 export { resolveWorkflowsDir as n, requireWorkflowsDir as t };

package/dist/{run-polling-DawiBus-.mjs → run-polling-C5fI7xTp.mjs}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
-import { O as InputValidationError, a as ui, y as toErrorMessage } from "./keystroke.mjs";
-import { a as readManifestsFromOutDir } from "./dist-CTEtWDW4.mjs";
-import { n as formatValidationError, o as validateRequiredFields, t as formatMissingInputError } from "./schema-display-FvI8QjOQ.mjs";
-import { n as sleep, t as TERMINAL_STATUSES } from "./run-polling-fBouPjJ2.mjs";
+import { A as InputValidationError, p as ui, x as toErrorMessage } from "./keystroke.mjs";
+import { a as readManifestsFromOutDir } from "./dist-BmbFJq8U.mjs";
+import { c as validateRequiredFields, n as formatMissingInputError, r as formatValidationError } from "./schema-display-sZ6ConJd.mjs";
+import { n as sleep, t as TERMINAL_STATUSES } from "./run-polling-1c0ckC1A.mjs";
 import * as path$1 from "node:path";
 import * as fs from "node:fs/promises";
 import { z } from "zod";
@@ -224,6 +224,17 @@ async function tryReadExistingInputSchema(workflowsDir, workflowName) {
 }
 //#endregion
 //#region src/commands/workflows/_shared/run-polling-render.ts
+/**
+* Live progress rendering for workflow runs (`workflows run --wait`, `--follow`, test polling).
+*
+* `pollForCompletion` fetches a full snapshot each tick (run status + all events + logs). This
+* module turns each snapshot into CLI hints; it does not affect execution or JSON output.
+*/
+const CORRELATION_ID_COLLATOR = new Intl.Collator("en", {
+	numeric: true,
+	sensitivity: "base"
+});
+const LOG_DISPLAY_ORDER = 35;
 function createRuntimeRenderState() {
 	return {
 		seenEventIds: /* @__PURE__ */ new Set(),
@@ -232,21 +243,92 @@ function createRuntimeRenderState() {
 		lastStatus: void 0
 	};
 }
+/**
+* Print any new logs, events, and run-status lines from one poll snapshot.
+*
+* Render order within a snapshot is intentional:
+* 1. Logs and events are facts observed during the run.
+* 2. Run status is a summary and must come last.
+*
+* On the final poll, `run.status` is often already `completed` while `events` still
+* contains step history we have not printed yet. Printing status first made it look like
+* the workflow finished before steps ran.
+*/
 function renderRunSnapshot(snapshot, state, verbose) {
+	const renderItems = buildNewRenderItems(snapshot, state);
+	for (const item of sortRenderItemsChronologically(renderItems)) if (item.kind === "log") {
+		state.seenLogIds.add(item.log.id);
+		renderRunLog(item.log, verbose);
+	} else {
+		state.seenEventIds.add(item.event.id);
+		renderRuntimeEvent(item.event, state.stepStates, verbose);
+	}
 	if (snapshot.run.status !== state.lastStatus) {
 		ui.hint(`Run status: ${snapshot.run.status}`);
 		state.lastStatus = snapshot.run.status;
 	}
-	for (const log of snapshot.logs) {
-		if (state.seenLogIds.has(log.id)) continue;
-		state.seenLogIds.add(log.id);
-		renderRunLog(log, verbose);
-	}
-	for (const event of snapshot.events) {
-		if (state.seenEventIds.has(event.id)) continue;
-		state.seenEventIds.add(event.id);
-		renderRuntimeEvent(event, state.stepStates, verbose);
-	}
+}
+function buildNewRenderItems(snapshot, state) {
+	const logs = snapshot.logs.filter((log) => !state.seenLogIds.has(log.id)).map((log) => ({
+		kind: "log",
+		log,
+		timestamp: log.timestamp,
+		correlationId: log.correlationId ?? "",
+		displayOrder: LOG_DISPLAY_ORDER,
+		id: log.id
+	}));
+	const events = snapshot.events.filter((event) => !state.seenEventIds.has(event.id)).map((event) => ({
+		kind: "event",
+		event,
+		timestamp: event.createdAt,
+		correlationId: event.correlationId,
+		displayOrder: eventTypeDisplayOrder(event.eventType),
+		id: event.id
+	}));
+	return [...logs, ...events];
+}
+function sortRenderItemsChronologically(items) {
+	return [...items].sort(compareRenderItemsChronologically);
+}
+/**
+* Display order for events that share a `createdAt` (common when the executor
+* persists a batch with one timestamp). Sorting by `id` alone is unsafe because
+* microsandbox event ids embed the type (`…:step_completed:1` < `…:step_started:1`).
+*/
+const EVENT_TYPE_DISPLAY_ORDER = {
+	trigger_transform: 5,
+	step_created: 10,
+	step_started: 20,
+	step_retrying: 30,
+	step_completed: 40,
+	step_failed: 50,
+	hook_created: 10,
+	hook_resumed: 40,
+	hook_cancelled: 50,
+	wait_created: 10,
+	wait_completed: 40,
+	stream_chunk: 35,
+	child_workflow_created: 10,
+	child_workflow_completed: 40,
+	child_workflow_failed: 50,
+	agent_created: 10,
+	agent_started: 20,
+	agent_completed: 40,
+	agent_failed: 50,
+	agent_cancelled: 50
+};
+function eventTypeDisplayOrder(eventType) {
+	return EVENT_TYPE_DISPLAY_ORDER[eventType];
+}
+/** Ascending timestamp, then correlation, lifecycle/log position, then id. */
+function compareRenderItemsChronologically(a, b) {
+	const timeDiff = Date.parse(a.timestamp) - Date.parse(b.timestamp);
+	if (timeDiff !== 0) return timeDiff;
+	const correlationDiff = CORRELATION_ID_COLLATOR.compare(a.correlationId, b.correlationId);
+	if (correlationDiff !== 0) return correlationDiff;
+	const displayOrderDiff = a.displayOrder - b.displayOrder;
+	if (displayOrderDiff !== 0) return displayOrderDiff;
+	return a.id.localeCompare(b.id);
 }
 function renderRunLog(log, verbose) {
 	const message = `${`log[${log.source}:${log.level}]`} ${log.message}`;
@@ -339,6 +421,7 @@ function toObject(value) {
 //#endregion
 //#region src/commands/workflows/_shared/run-polling.ts
 const POLL_INTERVAL_MS = 1e3;
+/** Poll until the run reaches a terminal status. When `render` is true, see `renderRunSnapshot`. */
 async function pollForCompletion(client, runId, timeoutSeconds, verbose, render = true) {
 	const deadline = Date.now() + timeoutSeconds * 1e3;
 	const renderState = createRuntimeRenderState();