@kici-dev/compiler 0.1.26 → 0.2.0

package/dist/commands/run-routed.js

@@ -0,0 +1,185 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { resolveKiciDir } from "../execution/executor.js";
+import "../execution/index.js";
+import { formatSummary } from "../remote/output/summary.js";
+import { detectOsMismatchHints } from "../local-plane/os-mismatch-hint.js";
+import { IN_PLACE_ROUTING_LABEL, TRUSTED_ROUTING_LABEL } from "../local-plane/scaler-config.js";
+import { planeLogPath } from "../local-plane/plane-manager.js";
+import { ensureLocalSource } from "../local-plane/plane-seed.js";
+import { triggerRun } from "../local-plane/plane-trigger.js";
+import { resolvePlaneForRun } from "../local-plane/resolve-plane.js";
+import { followRun } from "../local-plane/run-follow.js";
+import { seedLocalSecrets } from "../local-plane/secret-seed.js";
+import { resolveWorkdir } from "../local-plane/source-provider.js";
+import { injectRunsOnLabel } from "../local-plane/trusted-routing.js";
+import { compileCommand } from "./compile.js";
+import { withStdoutOnStderr } from "./run.js";
+import { renderRunBanner } from "./run-banner.js";
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import pc from "picocolors";
+import { logger, toErrorMessage } from "@kici-dev/core";
+//#region src/commands/run-routed.ts
+/**
+* `kici run --local [event]` — a real routed dispatch with this machine as the
+* ephemeral agent, through the warm local dev plane. In this phase only the
+* offline (independent) plane is wired; Platform attachment (`--connected` /
+* auto-select hybrid) lands with the attachment work.
+*
+* The offline path reuses the real orchestrator + agent pipeline end-to-end, so
+* the execution parity dividend (emit / cache / needs / parallel / `KICI_SOURCE_*`)
+* holds by construction — there is no second engine.
+*/
+/**
+* Entry point for the action-bearing `kici run`. Validates the routing flags and
+* drives the offline routed run. Returns true on run success.
+*/
+async function runRoutedCommand(options) {
+	if (options.debug) process.env.KICI_DEBUG = "true";
+	if (!options.local) {
+		logger.error(pc.red("kici run (connected cloud run) is not yet available. Use `kici run --local` for a routed run on this machine, or `kici run remote <fixture>` for the fixture path."));
+		return false;
+	}
+	if (!options.event) {
+		logger.error(pc.red("Provide an event to run, e.g. `kici run --local push`."));
+		return false;
+	}
+	return runRouted({
+		...options,
+		event: options.event
+	});
+}
+/**
+* Read a dispatch payload file `{ action?, client_payload? }`. Returns the
+* action + client_payload the routed dispatch trigger carries. An absent
+* `--payload` yields an empty action (a bare `dispatch()` workflow still
+* matches); a present file is parsed as JSON.
+*/
+function readDispatchPayload(payloadPath) {
+	if (!payloadPath) return {};
+	const raw = JSON.parse(readFileSync(payloadPath, "utf-8"));
+	return {
+		action: raw.action,
+		clientPayload: raw.client_payload
+	};
+}
+/** Drive the full routed run against the warm local plane (offline or attached). */
+async function runRouted(options) {
+	const quiet = Boolean(options.quiet);
+	const kiciDir = resolveKiciDir(options.kiciDir);
+	const repoRoot = path.resolve(kiciDir, "..");
+	if (!(quiet ? await withStdoutOnStderr(() => compileCommand({
+		kiciDir,
+		check: false,
+		verbose: options.debug ?? false,
+		quiet: true
+	})) : await compileCommand({
+		kiciDir,
+		check: false,
+		verbose: options.debug ?? false
+	}))) return false;
+	if (!quiet) try {
+		const os = await import("node:os");
+		const lockRaw = readFileSync(path.join(kiciDir, "kici.lock.json"), "utf-8");
+		const hints = detectOsMismatchHints(JSON.parse(lockRaw), os.platform(), os.arch());
+		for (const hint of hints) logger.warn(pc.yellow(hint));
+	} catch {}
+	let cleanup;
+	const restoreLocks = [];
+	try {
+		if (!quiet) logger.info(pc.dim("Starting the local dev plane…"));
+		const resolved = await resolvePlaneForRun({
+			offline: options.offline,
+			connected: options.connected
+		});
+		if ("error" in resolved) {
+			logger.error(pc.red(resolved.error));
+			return false;
+		}
+		const plane = resolved.plane;
+		if (!plane.url || !plane.adminToken) {
+			logger.error(pc.red("Local dev plane did not report a URL + admin token."));
+			return false;
+		}
+		const trusted = Boolean(options.trusted);
+		if (!quiet) logger.info(renderRunBanner(resolved.kind === "attached" ? {
+			mode: "attached",
+			planeUrl: plane.url,
+			orgId: resolved.orgId,
+			trusted
+		} : resolved.kind === "fallback" ? {
+			mode: "fallback",
+			planeUrl: plane.url,
+			fallbackReason: resolved.reason,
+			trusted
+		} : {
+			mode: "offline",
+			planeUrl: plane.url,
+			trusted
+		}));
+		const workdir = await resolveWorkdir({
+			inPlace: Boolean(options.inPlace),
+			repoRoot
+		});
+		cleanup = workdir.cleanup;
+		if (trusted) {
+			const lockPath = path.join(workdir.dir, ".kici", "kici.lock.json");
+			restoreLocks.push(injectRunsOnLabel(lockPath, TRUSTED_ROUTING_LABEL).restore);
+			if (options.inPlace) restoreLocks.push(injectRunsOnLabel(lockPath, IN_PLACE_ROUTING_LABEL).restore);
+		}
+		const seeded = await ensureLocalSource(plane.url, plane.adminToken, {
+			repoDir: workdir.dir,
+			inPlace: Boolean(options.inPlace)
+		});
+		const seededSecrets = await seedLocalSecrets(plane.url, plane.adminToken, {
+			orgId: seeded.orgId,
+			kiciDir
+		});
+		if (!quiet && seededSecrets.contexts.length > 0) logger.info(pc.dim(`Seeded ${seededSecrets.secretCount} local secret(s) across ${seededSecrets.contexts.length} context(s): ${seededSecrets.contexts.join(", ")}`));
+		if (!quiet) logger.info(pc.dim(`Triggering ${options.event} …`));
+		const dispatch = options.event === "dispatch" ? readDispatchPayload(options.payload) : void 0;
+		const runId = await triggerRun(plane.url, plane.adminToken, {
+			orgId: seeded.orgId,
+			sourceId: seeded.sourceName,
+			repoFullName: ".",
+			event: options.event === "dispatch" ? "dispatch" : options.event === "pull_request" ? "pull_request" : "push",
+			ref: workdir.ref,
+			sha: workdir.sha,
+			defaultBranch: workdir.branch,
+			...dispatch && {
+				action: dispatch.action,
+				clientPayload: dispatch.clientPayload
+			}
+		});
+		if (!quiet) logger.info(pc.green(`Run started: ${runId}`));
+		const outcome = await followRun(plane.url, plane.adminToken, runId, {
+			quiet,
+			onLine: (line) => process.stdout.write(line + "\n"),
+			hintLogPath: planeLogPath()
+		});
+		if (!quiet) {
+			const result = {
+				fixtureId: options.event,
+				runId,
+				status: outcome.status === "success" ? "success" : "failed",
+				totalDurationMs: 0,
+				jobs: outcome.jobs
+			};
+			process.stdout.write("\n" + formatSummary(result) + "\n");
+		}
+		return outcome.status === "success";
+	} catch (error) {
+		logger.error(pc.red(`\nError: ${toErrorMessage(error)}\n`));
+		if (options.debug && error instanceof Error && error.stack) logger.error(pc.gray(error.stack));
+		return false;
+	} finally {
+		for (const restore of restoreLocks.reverse()) try {
+			restore();
+		} catch {}
+		if (cleanup) await cleanup().catch(() => void 0);
+	}
+}
+//#endregion
+export { readDispatchPayload, runRoutedCommand };
+
+//# sourceMappingURL=run-routed.js.map

package/dist/commands/run.d.ts

@@ -1,15 +1,5 @@
 import { type HostTargetSelector, type InputsDescriptorMap } from '@kici-dev/engine';
-import type { RunLocalOptions } from '../local-executor/types.js';
 import type { RemoteRunOptions } from './preview.js';
-/**
- * Print a usage block for `kici run local` when the event argument is missing.
- *
- * Mirrors the discoverable help `kici preview` prints for a missing event: a
- * bold synopsis line, a one-line description, and a few concrete event
- * examples. The caller exits non-zero after printing — a missing event is a
- * usage error, unlike `kici preview` which treats no-event as help.
- */
-export declare function printRunLocalUsage(): void;
 /**
  * Compile `--target` selector strings into a {@link HostTargetSelector}. Each
  * string becomes one AND value (its own include set); repeated values
@@ -42,13 +32,6 @@ export declare function buildDispatchInputs(pairs: string[], descriptor: InputsD
  * stderr regardless.
  */
 export declare function withStdoutOnStderr<T>(fn: () => Promise<T>): Promise<T>;
-/**
- * Run a workflow locally using the local executor.
- * Thin wrapper that delegates to executeLocal from local-executor.
- *
- * Exit codes: 0 = success, 1 = job failure, 2 = config/compilation error
- */
-export declare function runLocalCommand(options: RunLocalOptions): Promise<boolean>;
 /**
  * Run fixtures remotely, routed through the Platform.
  */

package/dist/commands/run.js

@@ -4,51 +4,38 @@ import "../execution/index.js";
 import { loadGlobalConfig } from "../remote/config.js";
 import { RunHistory } from "../remote/history.js";
 import { buildLocalRepoIdentity } from "../remote/local-repo-identity.js";
-import { AccessDeniedError, AmbiguousClusterError, AuthenticationError, ConnectionError, NoClusterError, PlatformRunClient } from "../remote/platform-client.js";
+import { AccessDeniedError, AmbiguousClusterError, AuthenticationError, ConnectionError, NoClusterError, NotFoundError, PlatformRunClient } from "../remote/platform-client.js";
 import { buildEncryptedSecrets } from "../remote/secret-upload.js";
 import { createOverlayTarball, getSizeWarning, uploadTarball } from "../remote/uploader.js";
 import { formatJsonResult } from "../remote/output/json.js";
 import { formatJunitResult } from "../remote/output/junit.js";
 import { formatErrorHighlight, formatMultiFixtureSummary, formatSummary } from "../remote/output/summary.js";
-import { compileCommand } from "./compile.js";
 import { compileFixtures, filterFixtures } from "../fixtures/compiler.js";
 import { describeEvent } from "../fixtures/describe-event.js";
 import { FixturePickerCancelledError, runFixturePicker } from "../fixtures/picker.js";
 import { listHeldRunsForRun, resolveHeldRunContext } from "./held-run-client.js";
+import { compileCommand } from "./compile.js";
 import { handleNewHolds } from "./run-hold-watch.js";
 import path from "node:path";
 import pc from "picocolors";
 import { readFile, writeFile } from "node:fs/promises";
 import { formatBytes, logger, toErrorMessage } from "@kici-dev/core";
-import { coerceDispatchInputs, parseInputPairs } from "@kici-dev/engine";
+import { TERMINAL_RUN_STATES, coerceDispatchInputs, parseInputPairs, toCanonicalStatus } from "@kici-dev/engine";
 import { normalizeRunsOnToMatchers } from "@kici-dev/engine/labels/compile";
 import { confirm } from "@inquirer/prompts";
 //#region src/commands/run.ts
 /**
-* Print a usage block for `kici run local` when the event argument is missing.
+* True when the Platform run-status snapshot reports a terminal run status.
 *
-* Mirrors the discoverable help `kici preview` prints for a missing event: a
-* bold synopsis line, a one-line description, and a few concrete event
-* examples. The caller exits non-zero after printing — a missing event is a
-* usage error, unlike `kici preview` which treats no-event as help.
+* Resolves through the engine's canonical vocabulary rather than matching a
+* hand-written literal set: that is what makes the legacy `error` spelling
+* terminal without a second copy of the alias, and what stops a newly-added
+* terminal status leaving `kici run` polling a finished run forever.
 */
-function printRunLocalUsage() {
-	logger.info(pc.bold("\nUsage: kici run local <event> [options]\n"));
-	logger.info(pc.gray("Execute workflows locally for a given event, without orchestrator infrastructure.\n"));
-	logger.info(pc.gray("Examples:"));
-	logger.info(pc.gray("  kici run local push"));
-	logger.info(pc.gray("  kici run local pr:open"));
-	logger.info(pc.gray("  kici run local schedule"));
-	logger.info(pc.gray("  kici run local lifecycle:workflow_complete\n"));
-	logger.info(pc.gray("Or pick a workflow interactively: kici run local --pick\n"));
+function isTerminalRunStatus(status) {
+	const canonical = toCanonicalStatus(status.toLowerCase());
+	return canonical !== void 0 && TERMINAL_RUN_STATES.has(canonical);
 }
-/** Terminal run statuses returned by the Platform run-status snapshot. */
-const TERMINAL_STATUSES = /* @__PURE__ */ new Set([
-	"success",
-	"failed",
-	"cancelled",
-	"error"
-]);
 /**
 * Compile `--target` selector strings into a {@link HostTargetSelector}. Each
 * string becomes one AND value (its own include set); repeated values
@@ -109,6 +96,19 @@ function buildDispatchInputs(pairs, descriptor) {
 /** Interval between status/log polls while a run is active. */
 const POLL_INTERVAL_MS = 750;
 /**
+* How long a freshly triggered run may still read as missing before a 404 is
+* reported as a real error.
+*
+* The trigger call answers with the run id as soon as the orchestrator has
+* created the run, while the Platform's view of that run arrives over the
+* relay a moment later. The first poll therefore fires while the run is not
+* yet readable and legitimately 404s. Within this budget — and only until the
+* first successful read — a 404 means "not visible yet" and the poll retries;
+* after it, or once the run has been read at least once, a 404 is surfaced as
+* a genuinely missing run.
+*/
+const RUN_VISIBILITY_GRACE_MS = 3e4;
+/**
 * Run `fn` with everything written to `process.stdout` redirected to
 * `process.stderr`, then restore the original writer. Compiling a repo
 * evaluates every user workflow / fixture module, and a `console.log` at a
@@ -127,11 +127,11 @@ async function withStdoutOnStderr(fn) {
 	}
 }
 /**
-* Recompile `.kici/workflows` → `kici.lock.json` before a remote run, mirroring
-* `kici run local`. The orchestrator matches triggers and dispatches against the
-* inline lock, so a stale lock would route an edited or newly-added workflow
-* incorrectly. Returns false on a compile/validation error so the caller can
-* abort before any upload or dispatch.
+* Recompile `.kici/workflows` → `kici.lock.json` before a remote run. The
+* orchestrator matches triggers and dispatches against the inline lock, so a
+* stale lock would route an edited or newly-added workflow incorrectly. Returns
+* false on a compile/validation error so the caller can abort before any upload
+* or dispatch.
 */
 async function compileBeforeRemoteRun(options) {
 	const pureStdout = Boolean(options.json || options.quiet);
@@ -144,31 +144,6 @@ async function compileBeforeRemoteRun(options) {
 	return pureStdout ? withStdoutOnStderr(compile) : compile();
 }
 /**
-* Run a workflow locally using the local executor.
-* Thin wrapper that delegates to executeLocal from local-executor.
-*
-* Exit codes: 0 = success, 1 = job failure, 2 = config/compilation error
-*/
-async function runLocalCommand(options) {
-	if (options.debug) {
-		process.env.KICI_DEBUG = "true";
-		if (!options.quiet) logger.info(pc.gray("Debug mode enabled"));
-	}
-	try {
-		const { executeLocal } = await import("../local-executor/index.js");
-		return await executeLocal(options);
-	} catch (error) {
-		if (error instanceof Error && (error.message.includes("Cannot find module") || error.message.includes("ERR_MODULE_NOT_FOUND"))) {
-			logger.error(pc.red("Local executor not yet available. The local execution engine is under development."));
-			return false;
-		}
-		const message = toErrorMessage(error);
-		logger.error(pc.red(`\nError: ${message}\n`));
-		if (options.debug && error instanceof Error && error.stack) logger.error(pc.gray(error.stack));
-		return false;
-	}
-}
-/**
 * Run fixtures remotely, routed through the Platform.
 */
 async function runRemoteCommand(fixture, options) {
@@ -509,16 +484,27 @@ async function pollRunToCompletion(ctx, runId, fixtureId, options) {
 		let lastStatus = null;
 		const seenHolds = /* @__PURE__ */ new Set();
 		let heldCtx;
+		let runSeen = false;
 		while (!cancelled) {
-			const logs = await ctx.client.runLogs(ctx.orgId, runId, cursor, ctx.target);
+			let logs;
+			try {
+				logs = await ctx.client.runLogs(ctx.orgId, runId, cursor, ctx.target);
+				lastStatus = await ctx.client.runStatus(ctx.orgId, runId, ctx.target);
+			} catch (err) {
+				if (err instanceof NotFoundError && !runSeen && Date.now() - startTime < RUN_VISIBILITY_GRACE_MS) {
+					await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+					continue;
+				}
+				throw err;
+			}
+			runSeen = true;
 			for (const line of logs.lines) {
 				if (!options.quiet) process.stdout.write(line + "\n");
 				tailLines.push(line);
 				while (tailLines.length > MAX_TAIL) tailLines.shift();
 			}
 			cursor = logs.nextCursor;
-			lastStatus = await ctx.client.runStatus(ctx.orgId, runId, ctx.target);
-			const terminal = lastStatus.done || TERMINAL_STATUSES.has(lastStatus.status);
+			const terminal = lastStatus.done || isTerminalRunStatus(lastStatus.status);
 			if (terminal && logs.done) return finishRun(fixtureId, runId, lastStatus, startTime, tailLines, options);
 			if (!terminal) await watchRunHolds(runId, seenHolds, () => heldCtx, (c) => heldCtx = c, options);
 			await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
@@ -694,6 +680,6 @@ function displayRemoteResults(results) {
 	logger.info("");
 }
 //#endregion
-export { buildDispatchInputs, buildTargetSelector, lookupDispatchInputsDescriptor, printRunLocalUsage, runLocalCommand, runRemoteCommand, withStdoutOnStderr };
+export { buildDispatchInputs, buildTargetSelector, lookupDispatchInputsDescriptor, runRemoteCommand, withStdoutOnStderr };
 
 //# sourceMappingURL=run.js.map

package/dist/commands/runs/artifacts/download.d.ts

@@ -0,0 +1,24 @@
+export interface RunsArtifactsDownloadOptions {
+    archive?: boolean;
+    output?: string;
+}
+/** Basename an artifact takes under the output directory in the given mode. */
+export declare function destBasename(name: string, archive: boolean): string;
+/**
+ * Reduce a basename to the form a case-insensitive filesystem looks it up by.
+ *
+ * The NFC pass is deliberate defence for a widened artifact-name charset:
+ * `ArtifactNameSchema` accepts ASCII only today, so no live name can differ by
+ * normalisation — but HFS+ stores NFD and APFS folds case while preserving
+ * normalisation, so a non-ASCII name would collide on those volumes without it.
+ */
+export declare function foldBasename(basename: string): string;
+/**
+ * Group basenames that a case-insensitive filesystem resolves to one path.
+ *
+ * Groups appear in first-appearance order and each group is sorted; a basename
+ * with no partner is not reported.
+ */
+export declare function findCaseCollisions(basenames: string[]): string[][];
+export declare function runsArtifactsDownloadCommand(runId: string, name: string | undefined, options?: RunsArtifactsDownloadOptions): Promise<boolean>;
+//# sourceMappingURL=download.d.ts.map

package/dist/commands/runs/artifacts/download.js

@@ -0,0 +1,154 @@
+import "../../../rolldown-runtime-ClRpJifh.js";
+import { extractArtifactTarball } from "../../../remote/artifact-extract.js";
+import { DashboardClient, DashboardClientError } from "../../../remote/dashboard-client.js";
+import { isCaseInsensitiveDir } from "../../../remote/fs-case.js";
+import { join } from "node:path";
+import pc from "picocolors";
+import { mkdir, writeFile } from "node:fs/promises";
+import { logger, sha256, toErrorMessage } from "@kici-dev/core";
+import { ArtifactNameSchema } from "@kici-dev/engine";
+//#region src/commands/runs/artifacts/download.ts
+/** kici runs artifacts download — fetch one artifact (by name) or every artifact of a run. */
+/** Extension of the raw artifact archive written by `--archive`. */
+const ARCHIVE_EXTENSION = ".tar.gz";
+/** Basename an artifact takes under the output directory in the given mode. */
+function destBasename(name, archive) {
+	return archive ? `${name}${ARCHIVE_EXTENSION}` : name;
+}
+/**
+* Reduce a basename to the form a case-insensitive filesystem looks it up by.
+*
+* The NFC pass is deliberate defence for a widened artifact-name charset:
+* `ArtifactNameSchema` accepts ASCII only today, so no live name can differ by
+* normalisation — but HFS+ stores NFD and APFS folds case while preserving
+* normalisation, so a non-ASCII name would collide on those volumes without it.
+*/
+function foldBasename(basename) {
+	return basename.normalize("NFC").toLowerCase();
+}
+/**
+* Group basenames that a case-insensitive filesystem resolves to one path.
+*
+* Groups appear in first-appearance order and each group is sorted; a basename
+* with no partner is not reported.
+*/
+function findCaseCollisions(basenames) {
+	const byFold = /* @__PURE__ */ new Map();
+	for (const basename of basenames) {
+		const fold = foldBasename(basename);
+		const group = byFold.get(fold);
+		if (group) group.add(basename);
+		else byFold.set(fold, /* @__PURE__ */ new Set([basename]));
+	}
+	return [...byFold.values()].filter((g) => g.size > 1).map((g) => [...g].sort());
+}
+/**
+* Fetch a presigned artifact URL into a Buffer and verify its sha-256.
+*
+* NO `Authorization` header: `downloadUrl` is a presigned object-storage GET,
+* and the PAT authenticates to the Platform, not to object storage — attaching
+* it would leak the credential to the storage host. The bytes therefore flow
+* CLI <-> object storage directly and never transit the Platform.
+*/
+async function fetchArtifactBytes(entry) {
+	if (!entry.downloadUrl) throw new Error(`artifact "${entry.name}" has no download URL (the stored object is missing or expired)`);
+	const res = await fetch(entry.downloadUrl);
+	if (!res.ok) throw new Error(`download of "${entry.name}" failed (HTTP ${res.status})`);
+	const buf = Buffer.from(await res.arrayBuffer());
+	const actual = sha256(buf);
+	if (actual !== entry.sha256) throw new Error(`artifact "${entry.name}" checksum mismatch: expected ${entry.sha256}, got ${actual}`);
+	return buf;
+}
+/**
+* Refuse a listed name that is not a valid artifact name.
+*
+* Every name is validated against {@link ArtifactNameSchema} at upload, so a
+* response carrying one outside that contract comes from a broken or hostile
+* peer. The name becomes a path component under the output directory, so it is
+* checked before it is joined — an unchecked `../…` would let a list response
+* write anywhere on the caller's filesystem.
+*/
+function assertPathSafeName(name) {
+	if (!ArtifactNameSchema.safeParse(name).success) throw new Error(`listed artifact "${name}" is not a valid artifact name — refusing to write it under the output directory`);
+}
+/**
+* Refuse the whole invocation when two targets would land on the same path.
+*
+* Artifact names are case-sensitive, so a run can legitimately hold both
+* `bundle` and `Bundle`. On a filesystem that ignores case in path lookups the
+* two resolve to one path — the second extraction merges into the first's
+* directory, or overwrites its archive under `--archive`. The filesystem is
+* probed only once a fold collision is known to exist, so a case-sensitive
+* output directory downloads both exactly as before. A probe that cannot answer
+* is treated as case-insensitive: the collision is already certain, so the
+* unknown half is resolved towards refusing rather than towards losing data.
+*/
+async function assertNoCaseCollisions(targets, outDir, archive) {
+	const groups = findCaseCollisions(targets.map((t) => destBasename(t.name, archive)));
+	if (groups.length === 0) return;
+	let probeError;
+	let caseInsensitive = true;
+	try {
+		caseInsensitive = await isCaseInsensitiveDir(outDir);
+	} catch (err) {
+		probeError = err;
+	}
+	if (!caseInsensitive) return;
+	const pairs = groups.map((g) => g.map((basename) => `"${basename}"`).join(" and ")).join("; ");
+	const consequence = archive ? "writing both would overwrite one file with the other" : "extracting both would merge them into one directory";
+	const reason = probeError !== void 0 ? `the output directory ${outDir} could not be checked for case sensitivity (${toErrorMessage(probeError)})` : `the output directory ${outDir} is on a case-insensitive filesystem`;
+	throw new Error(`this run holds artifacts whose names differ only in case: ${pairs} — ${consequence}, and ${reason}. Download them one at a time into separate directories: kici runs artifacts download <run-id> <name> -o <dir>`);
+}
+/** Fetch one entry and write it to `outDir`, extracted or as the raw archive. */
+async function writeOne(entry, outDir, archive) {
+	assertPathSafeName(entry.name);
+	const buf = await fetchArtifactBytes(entry);
+	await mkdir(outDir, { recursive: true });
+	const dest = join(outDir, destBasename(entry.name, archive));
+	if (archive) {
+		await writeFile(dest, buf);
+		console.log(pc.green(`✓ ${entry.name} → ${dest}`));
+		return;
+	}
+	await extractArtifactTarball(buf, dest);
+	console.log(pc.green(`✓ ${entry.name} → ${dest}/`));
+}
+/** Resolve which listed artifacts the invocation targets. */
+function resolveTargets(artifacts, name, runId) {
+	if (!name) return artifacts;
+	const match = artifacts.find((a) => a.name === name);
+	if (match) return [match];
+	const names = artifacts.map((a) => a.name).join(", ") || "(none)";
+	throw new Error(`artifact "${name}" not found in run ${runId}. Available: ${names}`);
+}
+async function runsArtifactsDownloadCommand(runId, name, options = {}) {
+	try {
+		const { artifacts } = await (await DashboardClient.load()).listArtifacts(runId);
+		const outDir = options.output ?? process.cwd();
+		const downloadingAll = !name;
+		const targets = resolveTargets(artifacts, name, runId);
+		if (targets.length === 0) {
+			console.log(pc.gray("No artifacts for this run."));
+			return true;
+		}
+		for (const entry of targets) assertPathSafeName(entry.name);
+		if (downloadingAll) await assertNoCaseCollisions(targets.filter((t) => t.downloadUrl), outDir, options.archive ?? false);
+		let failures = 0;
+		for (const entry of targets) {
+			if (downloadingAll && !entry.downloadUrl) {
+				logger.warn(pc.yellow(`! ${entry.name} skipped — no download URL (object missing or expired)`));
+				failures++;
+				continue;
+			}
+			await writeOne(entry, outDir, options.archive ?? false);
+		}
+		return failures < targets.length;
+	} catch (err) {
+		logger.error(pc.red(err instanceof DashboardClientError ? err.message : toErrorMessage(err)));
+		return false;
+	}
+}
+//#endregion
+export { destBasename, findCaseCollisions, foldBasename, runsArtifactsDownloadCommand };
+
+//# sourceMappingURL=download.js.map

package/dist/commands/runs/artifacts/list.d.ts

@@ -0,0 +1,5 @@
+export interface RunsArtifactsListOptions {
+    json?: boolean;
+}
+export declare function runsArtifactsListCommand(runId: string, options?: RunsArtifactsListOptions): Promise<boolean>;
+//# sourceMappingURL=list.d.ts.map

package/dist/commands/runs/artifacts/list.js

@@ -0,0 +1,47 @@
+import "../../../rolldown-runtime-ClRpJifh.js";
+import { DashboardClient, DashboardClientError } from "../../../remote/dashboard-client.js";
+import { relativeTime, renderTable } from "../../../remote/render.js";
+import pc from "picocolors";
+import { formatBytes, logger, toErrorMessage } from "@kici-dev/core";
+//#region src/commands/runs/artifacts/list.ts
+/** kici runs artifacts list — the artifacts a run uploaded (the rows the dashboard Artifacts tab shows). */
+/** Number of leading sha-256 hex chars shown in the table (full digest via --json). */
+const SHA_PREFIX_LENGTH = 12;
+async function runsArtifactsListCommand(runId, options = {}) {
+	try {
+		const result = await (await DashboardClient.load()).listArtifacts(runId);
+		if (options.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return true;
+		}
+		if (result.artifacts.length === 0) {
+			console.log(pc.gray("No artifacts for this run."));
+			return true;
+		}
+		const rows = result.artifacts.map((a) => [
+			a.name,
+			a.jobId,
+			formatBytes(a.sizeBytes),
+			a.sha256.slice(0, SHA_PREFIX_LENGTH),
+			relativeTime(a.createdAt),
+			a.downloadUrl ? "" : pc.yellow("unavailable")
+		]);
+		console.log(renderTable([
+			"name",
+			"job",
+			"size",
+			"sha-256",
+			"created",
+			""
+		], rows));
+		console.log(pc.gray(`\n${result.artifacts.length} artifact(s). Download with kici runs artifacts download ${runId} <name>`));
+		return true;
+	} catch (err) {
+		logger.error(pc.red(err instanceof DashboardClientError ? err.message : toErrorMessage(err)));
+		return false;
+	}
+}
+//#endregion
+export { runsArtifactsListCommand };
+
+//# sourceMappingURL=list.js.map

package/dist/commands/runs/cancel.js

@@ -18,8 +18,8 @@ async function runsCancelCommand(runId, options = {}) {
 			return false;
 		}
 		logger.info(`${options.force ? "Force-cancelling" : "Cancelling"} run ${pc.cyan(runId)}...`);
-		const { cancelledJobs = 0 } = await client.cancelRun(runId, options.force ?? false);
-		console.log(pc.green(`Run ${runId} cancelled (${cancelledJobs} job${cancelledJobs !== 1 ? "s" : ""} affected).`));
+		const { cancelledJobs = 0, alreadyTerminal } = await client.cancelRun(runId, options.force ?? false);
+		console.log(alreadyTerminal ? pc.yellow(`Run ${runId} had already finished; nothing was cancelled.`) : pc.green(`Run ${runId} cancelled (${cancelledJobs} job${cancelledJobs !== 1 ? "s" : ""} affected).`));
 		return true;
 	} catch (err) {
 		logger.error(pc.red(err instanceof DashboardClientError ? err.message : toErrorMessage(err)));

package/dist/commands/runs/list.js

@@ -15,7 +15,13 @@ async function runsListCommand(options = {}) {
 			return true;
 		}
 		if (page.runs.length === 0) {
-			console.log(pc.gray("No runs found."));
+			const activity = await client.getWebhookActivity().catch(() => null);
+			if (activity && activity.received > 0) {
+				const win = activity.windowMinutes === 60 ? "the last hour" : `the last ${activity.windowMinutes} minutes`;
+				const headline = activity.orchestratorUnavailable || activity.matched === void 0 ? `${activity.received} webhooks received in ${win} but none produced a run` : `${activity.received} webhooks received in ${win}, ${activity.matched} matched`;
+				console.log(pc.yellow(`${headline}.`));
+				console.log(pc.gray(`Run ${pc.cyan("kici preview push")} to test your triggers locally.`));
+			} else console.log(pc.gray("No runs found."));
 			return true;
 		}
 		const rows = page.runs.map((r) => [
@@ -36,7 +42,7 @@ async function runsListCommand(options = {}) {
 			"started",
 			"duration"
 		], rows));
-		console.log(pc.gray(`\nPage ${page.page} · ${page.runs.length} of ${page.total}${page.hasMore ? " (more — use --page)" : ""}`));
+		console.log(pc.gray(`\n${page.runs.length} of ~${page.approxTotal} runs${page.nextCursor ? `  (more — use --cursor ${page.nextCursor})` : ""}`));
 		return true;
 	} catch (err) {
 		logger.error(pc.red(err instanceof DashboardClientError ? err.message : toErrorMessage(err)));