@kici-dev/compiler 0.5.0 → 0.6.1

package/dist/cli.js

@@ -4,10 +4,10 @@ import { shouldSuppressBanner } from "./cli-banner.js";
 import { fileURLToPath } from "node:url";
 import { resolve } from "node:path";
 import { realpathSync } from "node:fs";
-import { Argument, Command, Option } from "commander";
+import { Argument, Command } from "commander";
 import pc from "picocolors";
 //#region src/cli.ts
-const version = "0.5.0";
+const version = "0.6.1";
 /**
 * Top-level commands that were removed, mapped to their current equivalent.
 * Consulted when the CLI hits an unknown command so the user gets a precise
@@ -139,7 +139,7 @@ function buildProgram() {
 		const success = await previewCommand(event, options);
 		process.exit(success ? 0 : 1);
 	});
-	program.command("init").description("Initialize .kici/ directory with default workflows").option("--force", "Overwrite existing .kici/ directory", false).option("--skip-install", "Create files without installing dependencies", false).option("--package-manager <npm|pnpm|yarn>", "Force a package manager for the install step (default: auto-detect)").option("--mjs", "JavaScript-only mode (no TypeScript, no dependencies)", false).option("--workspace", "Integrate .kici/ into the detected pnpm/npm/yarn workspace so workflows can import sibling packages", false).option("--standalone", "Force a self-contained .kici/ even inside a workspace", false).option("--no-agents-md", "Skip writing .kici/AGENTS.md (LLM authoring context)").option("--private-registry <url>", "Scaffold a workflow registries: entry pointing at <url>").option("--private-registry-scope <scope>", "Optional npm package scope (e.g. @my-org) for the private registry").option("--private-registry-secret <ref>", "Qualified secret reference (env:NAME) the private registry token comes from", "production:NPM_TOKEN").addOption(new Option("--use-verdaccio-local").default(false).hideHelp()).action(async (options) => {
+	program.command("init").description("Initialize .kici/ directory with default workflows").option("--force", "Overwrite existing .kici/ directory", false).option("--skip-install", "Create files without installing dependencies", false).option("--package-manager <npm|pnpm|yarn>", "Force a package manager for the install step (default: auto-detect)").option("--mjs", "JavaScript-only mode (no TypeScript, no dependencies)", false).option("--workspace", "Integrate .kici/ into the detected pnpm/npm/yarn workspace so workflows can import sibling packages", false).option("--standalone", "Force a self-contained .kici/ even inside a workspace", false).option("--no-agents-md", "Skip writing .kici/AGENTS.md (LLM authoring context)").option("--private-registry <url>", "Scaffold a workflow registries: entry pointing at <url>").option("--private-registry-scope <scope>", "Optional npm package scope (e.g. @my-org) for the private registry").option("--private-registry-secret <ref>", "Qualified secret reference (env:NAME) the private registry token comes from", "production:NPM_TOKEN").action(async (options) => {
 		const { initCommand } = await import("./commands/index.js");
 		const success = await initCommand({
 			...options,
@@ -355,7 +355,7 @@ Environment variables:
 		const success = await runsListCommand(options);
 		process.exit(success ? 0 : 1);
 	});
-	runsCommand.command("show").argument("<run-id>", "Run ID to inspect").description("Show a run summary with its jobs and steps").option("--json", "Output raw JSON", false).action(async (runId, options) => {
+	runsCommand.command("show").argument("<run-id>", "Run ID to inspect").description("Show a run summary with its jobs and steps, why a job did not run, and any approval hold").option("--json", "Output raw JSON", false).action(async (runId, options) => {
 		const { runsShowCommand } = await import("./commands/index.js");
 		const success = await runsShowCommand(runId, { json: options.json });
 		process.exit(success ? 0 : 1);
@@ -396,19 +396,23 @@ Environment variables:
 		});
 		process.exit(success ? 0 : 1);
 	});
-	program.command("approve").argument("<run-id>", "Run ID whose approval gate to approve").description("Approve a held approval gate for a run").option("--job <name>", "Approve the hold for a specific job").option("--step <index>", "Approve a step-scoped hold (requires --job)").action(async (runId, options) => {
+	program.command("approve").argument("<run-id>", "Run ID whose approval gate to approve").description("Approve a held approval gate for a run").option("--job <name>", "Approve the hold for a specific job").option("--step <index>", "Approve a step-scoped hold (requires --job)").option("--hold-type <type>", "Approve the hold of this type (reviewer, timer, concurrency, security) — a job can carry two").option("--hold <id>", "Approve one hold by its id, as listed when nothing else separates them").action(async (runId, options) => {
 		const { approveCommand } = await import("./commands/index.js");
 		const success = await approveCommand(runId, {
 			job: options.job,
-			step: options.step
+			step: options.step,
+			hold: options.hold,
+			holdType: options.holdType
 		});
 		process.exit(success ? 0 : 1);
 	});
-	program.command("reject").argument("<run-id>", "Run ID whose approval gate to reject").description("Reject a held approval gate for a run").option("--job <name>", "Reject the hold for a specific job").option("--step <index>", "Reject a step-scoped hold (requires --job)").requiredOption("--reason <text>", "Reason for the rejection").action(async (runId, options) => {
+	program.command("reject").argument("<run-id>", "Run ID whose approval gate to reject").description("Reject a held approval gate for a run").option("--job <name>", "Reject the hold for a specific job").option("--step <index>", "Reject a step-scoped hold (requires --job)").option("--hold-type <type>", "Reject the hold of this type (reviewer, timer, concurrency, security) — a job can carry two").option("--hold <id>", "Reject one hold by its id, as listed when nothing else separates them").requiredOption("--reason <text>", "Reason for the rejection").action(async (runId, options) => {
 		const { rejectCommand } = await import("./commands/index.js");
 		const success = await rejectCommand(runId, {
 			job: options.job,
 			step: options.step,
+			hold: options.hold,
+			holdType: options.holdType,
 			reason: options.reason
 		});
 		process.exit(success ? 0 : 1);
@@ -440,6 +444,32 @@ Environment variables:
 		});
 		process.exit(success ? 0 : 1);
 	});
+	const reportCmd = program.command("report").description("Gather a redacted diagnostic bundle to share when reporting an issue");
+	reportCmd.enablePositionalOptions();
+	reportCmd.option("--run <id>", "Scope the bundle to a failing run").option("-o, --output <path>", "Where to write the bundle ZIP").option("--metadata <key=value>", "Attach metadata (repeatable)", (v, p) => [...p, v], []).option("--no-redact", "Do NOT redact secrets (prints a loud warning)").option("--upload", "Upload the bundle privately to KiCI and print a reference id").option("--message <text>", "Describe the problem (sent with --upload)").option("--email <address>", "Contact address for follow-up (sent with --upload)").option("--kici-dir <path>", "Path to the .kici directory", ".kici").action(async (options) => {
+		const { reportCommand } = await import("./commands/index.js");
+		const ok = await reportCommand({
+			output: options.output,
+			run: options.run,
+			metadata: options.metadata,
+			redact: options.redact !== false,
+			upload: options.upload,
+			message: options.message,
+			email: options.email,
+			kiciDir: options.kiciDir
+		});
+		process.exit(ok ? 0 : 1);
+	});
+	reportCmd.command("list").description("List the issue reports you have uploaded").option("--json", "Output raw JSON", false).action(async (options) => {
+		const { reportListCommand } = await import("./commands/index.js");
+		const ok = await reportListCommand({ json: options.json });
+		process.exit(ok ? 0 : 1);
+	});
+	reportCmd.command("withdraw").argument("<ref>", "Reference id of the report to withdraw").description("Withdraw an uploaded report and delete its bundle").action(async (ref) => {
+		const { reportWithdrawCommand } = await import("./commands/index.js");
+		const ok = await reportWithdrawCommand({ ref });
+		process.exit(ok ? 0 : 1);
+	});
 	program.command("workflows").description("Manage workflow registrations").command("list").description("List permanently registered workflows").option("--json", "Output as JSON", false).option("--stale <duration>", "Filter stale registrations (e.g., 30d, 7d)").option("--trigger-type <type>", "Filter by trigger type").option("--repo <repo>", "Filter by repository").action(async (options) => {
 		const { workflowsListCommand } = await import("./commands/index.js");
 		const success = await workflowsListCommand({
@@ -454,7 +484,7 @@ Environment variables:
 		const { docsCommand } = await import("./commands/index.js");
 		const success = await docsCommand({ open: options.open });
 		process.exit(success ? 0 : 1);
-	}).command("llm [topic]").description("Print KiCI LLM docs bundles. No topic prints the llms.txt index; <topic> prints a task bundle (e.g. sdk, cli, patterns, features, providers, architecture, getting-started); \"full\" prints the complete bundle.").option("--out <path>", "Write the bundle to a file instead of stdout").action(async (topic, options) => {
+	}).command("llm [topic]").description("Print KiCI LLM docs bundles. No topic prints the llms.txt index; <topic> prints a task bundle (e.g. sdk, cli, cli-remote, patterns, features, providers, architecture, getting-started); \"full\" prints the complete bundle.").option("--out <path>", "Write the bundle to a file instead of stdout").action(async (topic, options) => {
 		const { docsLlmCommand } = await import("./commands/index.js");
 		const success = await docsLlmCommand({
 			topic,
@@ -462,6 +492,14 @@ Environment variables:
 		});
 		process.exit(success ? 0 : 1);
 	});
+	program.command("feedback").description("Print how to report a discrepancy between what KiCI advertises and what it does. Files nothing.").option("--open", "Open the prefilled issue form in the default browser").option("--json", "Emit the reporting contract as JSON").action(async (options) => {
+		const { feedbackCommand } = await import("./commands/index.js");
+		const success = await feedbackCommand({
+			open: options.open,
+			json: options.json
+		});
+		process.exit(success ? 0 : 1);
+	});
 	program.command("admin").description("Operator-facing commands for running instances").command("drain-worker").description("Trigger graceful drain on a worker instance").requiredOption("--url <url>", "Worker URL (e.g., http://worker-host:<port>)").action(async (options) => {
 		const { drainWorkerCommand } = await import("./commands/index.js");
 		const success = await drainWorkerCommand({ url: options.url });

package/dist/commands/approve.d.ts

@@ -11,6 +11,18 @@ export interface ApproveOptions {
     job?: string;
     /** Match a step-scoped hold by its step index. */
     step?: string;
+    /**
+     * Match one hold by its own id. The escape hatch for an ambiguity nothing
+     * else resolves; the error listing prints the ids when it needs to.
+     */
+    hold?: string;
+    /**
+     * Narrow to holds of one type (`reviewer` / `timer` / `concurrency` /
+     * `security`). A job carrying an SDK `requireApproval` AND a security-typed
+     * context gate has two pending holds under one job name, and this is what
+     * separates them.
+     */
+    holdType?: string;
 }
 /**
  * Approve a held approval gate.

package/dist/commands/approve.js

@@ -22,9 +22,12 @@ async function approveCommand(runId, options = {}) {
 	try {
 		const ctx = await resolveHeldRunContext();
 		if (!ctx) return false;
-		const resolution = resolveHeldRunId(await listHeldRunsForRun(ctx, runId), {
+		const holds = await listHeldRunsForRun(ctx, runId);
+		const resolution = resolveHeldRunId(holds, {
 			job: options.job,
-			step: options.step
+			step: options.step,
+			holdId: options.hold,
+			holdType: options.holdType
 		});
 		if (!resolution.ok) {
 			logger.error(pc.red(resolution.error));

package/dist/commands/compile.js

@@ -60,7 +60,8 @@ async function compileCommand(options) {
 		if (existsSync(path.join(absoluteKiciDir, "package.json"))) {
 			const existingHash = await readExistingLockfileHash(lockPath);
 			if (existingHash) {
-				const currentHash = computeLockfileHash(detectGitRoot());
+				const gitRoot = detectGitRoot();
+				const currentHash = computeLockfileHash(gitRoot);
 				if (currentHash && currentHash !== existingHash) {
 					logger.info(pc.yellow("Dependencies changed") + " — reinstalling before compile...");
 					await reinstallDeps(absoluteKiciDir);
@@ -75,7 +76,8 @@ async function compileCommand(options) {
 			return false;
 		}
 		if (options.verbose) logger.debug(pc.dim("Validation passed"));
-		const lockJson = serializeLockFile(generateLockFile(workflowsWithSource));
+		const lockFile = generateLockFile(workflowsWithSource);
+		const lockJson = serializeLockFile(lockFile);
 		const windowWarning = schemaWindowWarning(BREAKING_FLOOR, SCHEMA_VERSION);
 		if (windowWarning) logger.warn(pc.yellow(windowWarning));
 		if (!options.check) {

package/dist/commands/doctor.js

@@ -20,7 +20,7 @@ import { promisify } from "node:util";
 * Platform API is required.
 */
 const execFileAsync = promisify(execFile);
-const SEVEN_DAYS_MS = 10080 * 60 * 1e3;
+const SEVEN_DAYS_MS = 6048e5;
 /** Is a stored token + endpoint present (regardless of expiry)? */
 function hasCredentials(config) {
 	return Boolean((config.pat ?? config.token) && (config.platformEndpoint ?? config.endpoint));
@@ -47,7 +47,7 @@ function checkLogin(config, now) {
 			if (expiresAt - now < SEVEN_DAYS_MS) return {
 				name,
 				status: "warn",
-				message: `Access token expires in ${Math.ceil((expiresAt - now) / (1440 * 60 * 1e3))} day(s).`,
+				message: `Access token expires in ${Math.ceil((expiresAt - now) / 864e5)} day(s).`,
 				nextCommand: "kici login"
 			};
 		}

package/dist/commands/endpoints.js

@@ -119,12 +119,10 @@ function categorizeTrigger(workflowName, trigger, groups) {
 				eventName: `workflows_failed_batch${trigger.name ? `:${trigger.name}` : ""}`
 			});
 			break;
-		case "job_complete":
-			groups.kiciEvent.push({
-				workflowName,
-				eventName: `job_complete${trigger.workflow ? `:${trigger.workflow}` : ""}${trigger.job ? `.${trigger.job}` : ""}`
-			});
-			break;
+		case "job_complete": groups.kiciEvent.push({
+			workflowName,
+			eventName: `job_complete${trigger.workflow ? `:${trigger.workflow}` : ""}${trigger.job ? `.${trigger.job}` : ""}`
+		});
 	}
 }
 /**

package/dist/commands/feedback.d.ts

@@ -0,0 +1,53 @@
+/** The public tracker. Reports about KiCI itself go here — never customer data. */
+export declare const FEEDBACK_TRACKER_URL = "https://github.com/kici-dev/kici-public";
+/** The issue form tuned for an advertised-versus-actual report. */
+export declare const FEEDBACK_TEMPLATE = "agent_report.yml";
+export declare const FEEDBACK_NEW_ISSUE_URL = "https://github.com/kici-dev/kici-public/issues/new?template=agent_report.yml";
+/** Suspected vulnerabilities go here instead, privately. */
+export declare const FEEDBACK_SECURITY_ADVISORY_URL = "https://github.com/kici-dev/kici-public/security/advisories/new";
+export interface FeedbackField {
+    id: string;
+    label: string;
+    description: string;
+}
+export interface FeedbackContract {
+    tracker: string;
+    newIssueUrl: string;
+    template: string;
+    securityAdvisoryUrl: string;
+    guideUrl: string;
+    searchCommand: string;
+    approval: {
+        required: boolean;
+        rule: string;
+    };
+    qualifies: string[];
+    doesNotQualify: string[];
+    requiredFields: FeedbackField[];
+    prohibited: string[];
+    privateReportCommand: string;
+}
+/**
+ * The single definition of what a reportable discrepancy is and what a report
+ * must carry. `kici feedback` prints it, `--json` emits it verbatim, and
+ * hack/feedback-contract.test.ts asserts the published guide says the same
+ * thing — so the CLI and the doc cannot drift apart.
+ */
+export declare const FEEDBACK_CONTRACT: FeedbackContract;
+export interface FeedbackOptions {
+    /** Open the prefilled issue form in the default browser. */
+    open?: boolean;
+    /** Emit the contract as JSON on stdout instead of prose. */
+    json?: boolean;
+}
+/**
+ * Print the contract for reporting a KiCI discrepancy: what qualifies, what a
+ * report must carry, what must never appear in a public issue, and the rule
+ * that an agent drafts a report but a human decides to file it.
+ *
+ * The command reaches no network and files nothing. `--open` opens the
+ * prefilled issue form; `--json` emits the same contract for an agent to
+ * consume without parsing prose.
+ */
+export declare function feedbackCommand(options?: FeedbackOptions): Promise<boolean>;
+//# sourceMappingURL=feedback.d.ts.map

package/dist/commands/feedback.js

@@ -0,0 +1,142 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import pc from "picocolors";
+import { logger, toErrorMessage } from "@kici-dev/core";
+import open from "open";
+//#region src/commands/feedback.ts
+/** The public tracker. Reports about KiCI itself go here — never customer data. */
+const FEEDBACK_TRACKER_URL = "https://github.com/kici-dev/kici-public";
+/** The issue form tuned for an advertised-versus-actual report. */
+const FEEDBACK_TEMPLATE = "agent_report.yml";
+const FEEDBACK_NEW_ISSUE_URL = `${FEEDBACK_TRACKER_URL}/issues/new?template=${FEEDBACK_TEMPLATE}`;
+/** Suspected vulnerabilities go here instead, privately. */
+const FEEDBACK_SECURITY_ADVISORY_URL = `${FEEDBACK_TRACKER_URL}/security/advisories/new`;
+/**
+* The single definition of what a reportable discrepancy is and what a report
+* must carry. `kici feedback` prints it, `--json` emits it verbatim, and
+* hack/feedback-contract.test.ts asserts the published guide says the same
+* thing — so the CLI and the doc cannot drift apart.
+*/
+const FEEDBACK_CONTRACT = {
+	tracker: FEEDBACK_TRACKER_URL,
+	newIssueUrl: FEEDBACK_NEW_ISSUE_URL,
+	template: FEEDBACK_TEMPLATE,
+	securityAdvisoryUrl: FEEDBACK_SECURITY_ADVISORY_URL,
+	guideUrl: "https://kici.dev/docs/user/reporting-discrepancies/",
+	searchCommand: "gh issue list --repo kici-dev/kici-public --search \"<terms>\" --state all",
+	approval: {
+		required: true,
+		rule: "Draft the issue, show the full body to the person you are working with, and file it only after they say yes."
+	},
+	qualifies: [
+		"A documented flag, command, or option that does not exist in the version you ran.",
+		"Documented output — a shape, a field, an exit code — that differs from what the command produced.",
+		"A CLI --help description that contradicts the published docs.",
+		"A documented behaviour that does not happen, or a documented guarantee that does not hold.",
+		"A documented error or limit that the tool does not actually enforce."
+	],
+	doesNotQualify: [
+		"Usage questions, or behaviour you find surprising but that the docs describe correctly.",
+		"Feature requests and design preferences.",
+		"Anything you inferred from reading docs without running the command.",
+		"Anything reproduced only on a locally built or unreleased version.",
+		"A failure that is your workflow, your credentials, or your environment."
+	],
+	requiredFields: [
+		{
+			id: "advertised",
+			label: "What the docs or CLI advertise",
+			description: "The exact claim, quoted, plus its source: a docs URL or the command whose --help says it."
+		},
+		{
+			id: "observed",
+			label: "What actually happened",
+			description: "The real output or behaviour, quoted, with any error text."
+		},
+		{
+			id: "reproduction",
+			label: "Minimal reproduction, including setup",
+			description: "Every step from an empty directory: the setup commands, a minimal synthetic workflow, and the exact command you ran."
+		},
+		{
+			id: "version",
+			label: "Version and environment",
+			description: "Output of `kici --version`, plus Node version and OS."
+		},
+		{
+			id: "justification",
+			label: "Why this is a discrepancy",
+			description: "One or two sentences ruling out the likely misreads — why the docs cannot be read to match what you observed."
+		}
+	],
+	prohibited: [
+		"No secrets, tokens, or credentials — not even redacted-looking ones.",
+		"No private repository names, internal hostnames, organization ids, or run ids.",
+		"No log excerpts you have not read line by line.",
+		"Reproduce with a minimal synthetic workflow, never the real one you were working on."
+	],
+	privateReportCommand: "kici report --run <run-id> --upload"
+};
+function printContract() {
+	const c = FEEDBACK_CONTRACT;
+	logger.info(pc.bold("Reporting a KiCI discrepancy"));
+	logger.info("");
+	logger.info("Use this when the published docs or the CLI advertise one behaviour and KiCI does another.");
+	logger.info(`Tracker: ${c.tracker}`);
+	logger.info(`Full guide: ${c.guideUrl}`);
+	logger.info("");
+	logger.info(pc.bold("1. Search first"));
+	logger.info("Comment on an existing report rather than opening a second one.");
+	logger.info(`  ${c.searchCommand}`);
+	logger.info("");
+	logger.info(pc.bold("2. Check it qualifies"));
+	for (const item of c.qualifies) logger.info(`  ${pc.green("+")} ${item}`);
+	logger.info("  Not a discrepancy:");
+	for (const item of c.doesNotQualify) logger.info(`  ${pc.gray("-")} ${item}`);
+	logger.info("");
+	logger.info(pc.bold("3. Never file these publicly"));
+	logger.info(`  A suspected vulnerability is never a public issue — open a private advisory instead:\n    ${c.securityAdvisoryUrl}`);
+	logger.info(`  A problem with your own runs is not a tracker issue — send it privately instead:\n    ${c.privateReportCommand}`);
+	for (const rule of c.prohibited) logger.info(`  ${pc.yellow("!")} ${rule}`);
+	logger.info("");
+	logger.info(pc.bold("4. Draft the report"));
+	for (const field of c.requiredFields) {
+		logger.info(`  ${field.label}`);
+		logger.info(pc.gray(`    ${field.description}`));
+	}
+	logger.info("");
+	logger.info(pc.bold("5. Get approval, then file"));
+	logger.info(`  ${c.approval.rule}`);
+	logger.info(`  Form: ${c.newIssueUrl}`);
+	logger.info(pc.gray(`  Or: kici feedback --open`));
+	logger.info("");
+	logger.info(pc.gray("Machine-readable: kici feedback --json"));
+}
+/**
+* Print the contract for reporting a KiCI discrepancy: what qualifies, what a
+* report must carry, what must never appear in a public issue, and the rule
+* that an agent drafts a report but a human decides to file it.
+*
+* The command reaches no network and files nothing. `--open` opens the
+* prefilled issue form; `--json` emits the same contract for an agent to
+* consume without parsing prose.
+*/
+async function feedbackCommand(options = {}) {
+	if (options.json) {
+		process.stdout.write(`${JSON.stringify(FEEDBACK_CONTRACT, null, 2)}\n`);
+		return true;
+	}
+	printContract();
+	if (!options.open) return true;
+	try {
+		await open(FEEDBACK_NEW_ISSUE_URL);
+		return true;
+	} catch (error) {
+		logger.error(pc.red(`Could not open a browser: ${toErrorMessage(error)}`));
+		logger.info(pc.gray(`Open ${FEEDBACK_NEW_ISSUE_URL} manually.`));
+		return false;
+	}
+}
+//#endregion
+export { FEEDBACK_CONTRACT, FEEDBACK_NEW_ISSUE_URL, FEEDBACK_SECURITY_ADVISORY_URL, FEEDBACK_TEMPLATE, FEEDBACK_TRACKER_URL, feedbackCommand };
+
+//# sourceMappingURL=feedback.js.map

package/dist/commands/held-run-client.d.ts

@@ -6,6 +6,19 @@
  * API.
  */
 import type { HeldRunSummary } from '@kici-dev/engine';
+/**
+ * A failed held-runs request, carrying the HTTP status so a caller can tell a
+ * caller who will NEVER have the data (401 / 403 — no permission on the
+ * held-runs surface) from a transport or server failure that may succeed next
+ * time. `kici runs show` reads holds as optional detail, and reminding such a
+ * caller on every single invocation is noise, not information.
+ */
+export declare class HeldRunRequestError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+    /** True when the caller lacks permission — retrying changes nothing. */
+    get isPermissionDenied(): boolean;
+}
 /** Resolved auth context for a held-run command. */
 export interface HeldRunContext {
     endpoint: string;
@@ -15,8 +28,15 @@ export interface HeldRunContext {
 /**
  * Resolve the auth context, printing a clear error and returning null when the
  * CLI is not authenticated / no active org is set.
+ *
+ * `quiet` suppresses the error output for a caller whose own command does not
+ * depend on the held-run surface — `kici runs show` reads holds as extra
+ * detail on a run it can already display, so an unresolvable context must not
+ * make it print an authentication error for a command that worked.
  */
-export declare function resolveHeldRunContext(): Promise<HeldRunContext | null>;
+export declare function resolveHeldRunContext(options?: {
+    quiet?: boolean;
+}): Promise<HeldRunContext | null>;
 /** List the held runs for a single run id. */
 export declare function listHeldRunsForRun(ctx: HeldRunContext, runId: string): Promise<HeldRunSummary[]>;
 /**

package/dist/commands/held-run-client.js

@@ -11,25 +11,44 @@ import { logger } from "@kici-dev/core";
 * API.
 */
 /**
+* A failed held-runs request, carrying the HTTP status so a caller can tell a
+* caller who will NEVER have the data (401 / 403 — no permission on the
+* held-runs surface) from a transport or server failure that may succeed next
+* time. `kici runs show` reads holds as optional detail, and reminding such a
+* caller on every single invocation is noise, not information.
+*/
+var HeldRunRequestError = class extends Error {
+	status;
+	constructor(message, status) {
+		super(message);
+		this.status = status;
+		this.name = "HeldRunRequestError";
+	}
+	/** True when the caller lacks permission — retrying changes nothing. */
+	get isPermissionDenied() {
+		return this.status === 401 || this.status === 403;
+	}
+};
+/**
 * Resolve the auth context, printing a clear error and returning null when the
 * CLI is not authenticated / no active org is set.
+*
+* `quiet` suppresses the error output for a caller whose own command does not
+* depend on the held-run surface — `kici runs show` reads holds as extra
+* detail on a run it can already display, so an unresolvable context must not
+* make it print an authentication error for a command that worked.
 */
-async function resolveHeldRunContext() {
+async function resolveHeldRunContext(options = {}) {
 	const config = await loadGlobalConfig();
-	const token = config.pat ?? config.token;
-	if (!token) {
-		logger.error(pc.red("Not authenticated. Run `kici login` to get started."));
+	const fail = (message) => {
+		if (!options.quiet) logger.error(pc.red(message));
 		return null;
-	}
+	};
+	const token = config.pat ?? config.token;
+	if (!token) return fail("Not authenticated. Run `kici login` to get started.");
 	const endpoint = config.platformEndpoint ?? config.endpoint;
-	if (!endpoint) {
-		logger.error(pc.red("No endpoint configured. Run `kici login` to configure."));
-		return null;
-	}
-	if (!config.activeOrgId) {
-		logger.error(pc.red("No active organization. Run `kici org use <name>` to set one."));
-		return null;
-	}
+	if (!endpoint) return fail("No endpoint configured. Run `kici login` to configure.");
+	if (!config.activeOrgId) return fail("No active organization. Run `kici org use <name>` to set one.");
 	return {
 		endpoint,
 		token,
@@ -49,7 +68,7 @@ async function listHeldRunsForRun(ctx, runId) {
 		method: "GET",
 		headers: authHeaders(ctx.token)
 	});
-	if (!response.ok) throw new Error(await describeError(response));
+	if (!response.ok) throw new HeldRunRequestError(await describeError(response), response.status);
 	return (await response.json()).heldRuns ?? [];
 }
 /**
@@ -99,6 +118,6 @@ async function describeError(response) {
 	}
 }
 //#endregion
-export { listHeldRunsForRun, postApprove, postReject, resolveHeldRunContext };
+export { HeldRunRequestError, listHeldRunsForRun, postApprove, postReject, resolveHeldRunContext };
 
 //# sourceMappingURL=held-run-client.js.map

package/dist/commands/hook.js

@@ -31,27 +31,28 @@ async function hookInstallCommand(options = {}) {
 		if (options.git) selectedTool = "git";
 		else {
 			const tools = await detectHookTools();
-			if (tools.length === 0) if (process.stdout.isTTY && !isCiEnvironment()) {
-				const choice = await select({
-					message: "No pre-commit tool detected. How would you like to install the hook?",
-					choices: [{
-						name: "Raw git hook (.git/hooks/pre-commit)",
-						value: "git"
-					}, {
-						name: "Skip installation",
-						value: "skip"
-					}]
-				});
-				if (choice === "skip") {
-					logger.info(pc.yellow("Hook installation skipped."));
+			if (tools.length === 0) {
+				if (process.stdout.isTTY && !isCiEnvironment()) {
+					const choice = await select({
+						message: "No pre-commit tool detected. How would you like to install the hook?",
+						choices: [{
+							name: "Raw git hook (.git/hooks/pre-commit)",
+							value: "git"
+						}, {
+							name: "Skip installation",
+							value: "skip"
+						}]
+					});
+					if (choice === "skip") {
+						logger.info(pc.yellow("Hook installation skipped."));
+						return true;
+					}
+					selectedTool = choice;
+				} else {
+					logger.info(pc.yellow("No pre-commit tool detected. Use --git to install raw git hook."));
 					return true;
 				}
-				selectedTool = choice;
-			} else {
-				logger.info(pc.yellow("No pre-commit tool detected. Use --git to install raw git hook."));
-				return true;
-			}
-			else if (tools.length === 1) {
+			} else if (tools.length === 1) {
 				selectedTool = tools[0].name;
 				logger.info(pc.gray(`Detected ${selectedTool}, installing hook...`));
 			} else if (process.stdout.isTTY && !isCiEnvironment()) selectedTool = await select({
@@ -87,7 +88,8 @@ async function hookInstallCommand(options = {}) {
 */
 async function detectVerdaccioNpmrc() {
 	try {
-		return (await readFile(path.resolve(".kici", ".npmrc"), "utf-8")).includes("verdaccio");
+		const npmrcPath = path.resolve(".kici", ".npmrc");
+		return (await readFile(npmrcPath, "utf-8")).includes("verdaccio");
 	} catch {
 		return false;
 	}

package/dist/commands/index.d.ts

@@ -40,6 +40,8 @@ export { diagnosticsCommand } from './diagnostics.js';
 export type { DiagnosticsOptions } from './diagnostics.js';
 export { doctorCommand } from './doctor.js';
 export type { DoctorOptions } from './doctor.js';
+export { reportCommand, reportListCommand, reportWithdrawCommand } from './report/index.js';
+export type { ReportOptions } from './report/index.js';
 export { orgListCommand, orgUseCommand, orgCurrentCommand } from './org.js';
 export { orchestratorsListCommand, orchestratorsUseCommand } from './orchestrators.js';
 export type { OrchestratorsOptions } from './orchestrators.js';
@@ -55,7 +57,9 @@ export type { WorkflowsListOptions } from './workflows.js';
 export { drainWorkerCommand } from './drain-worker.js';
 export type { DrainWorkerOptions } from './drain-worker.js';
 export { docsCommand, docsLlmCommand } from './docs.js';
+export { feedbackCommand, FEEDBACK_CONTRACT } from './feedback.js';
 export type { DocsOptions, DocsLlmOptions } from './docs.js';
+export type { FeedbackOptions, FeedbackContract, FeedbackField } from './feedback.js';
 export { verifyAttestationCommand } from './verify-attestation.js';
 export type { VerifyAttestationOptions } from './verify-attestation.js';
 export { notificationsChannelsListCommand, notificationsChannelsAddCommand, notificationsChannelsRemoveCommand, notificationsSubscriptionsListCommand, notificationsSubscriptionsAddCommand, notificationsSubscriptionsRemoveCommand, notificationsRosterListCommand, notificationsRosterAddCommand, notificationsRosterRemoveCommand, } from './notifications.js';

package/dist/commands/index.js

@@ -6,6 +6,7 @@ import { docsCommand, docsLlmCommand } from "./docs.js";
 import { doctorCommand } from "./doctor.js";
 import { drainWorkerCommand } from "./drain-worker.js";
 import { endpointsCommand } from "./endpoints.js";
+import { FEEDBACK_CONTRACT, feedbackCommand } from "./feedback.js";
 import { fixtureCommand } from "./fixture.js";
 import { hookInstallCommand } from "./hook.js";
 import { watchCommand } from "./watch.js";
@@ -24,6 +25,7 @@ import { runsCancelCommand } from "./runs/cancel.js";
 import { runsArtifactsListCommand } from "./runs/artifacts/list.js";
 import { runsArtifactsDownloadCommand } from "./runs/artifacts/download.js";
 import { typesCommand } from "./types.js";
+import { reportCommand, reportListCommand, reportWithdrawCommand } from "./report/index.js";
 import { orgCurrentCommand, orgListCommand, orgUseCommand } from "./org.js";
 import { orchestratorsListCommand, orchestratorsUseCommand } from "./orchestrators.js";
 import { localAttachCommand, localDetachCommand, localDownCommand, localLogsCommand, localStatusCommand, localUpCommand } from "./local.js";
@@ -33,4 +35,4 @@ import { rejectCommand } from "./reject.js";
 import { workflowsListCommand } from "./workflows.js";
 import { verifyAttestationCommand } from "./verify-attestation.js";
 import { notificationsChannelsAddCommand, notificationsChannelsListCommand, notificationsChannelsRemoveCommand, notificationsRosterAddCommand, notificationsRosterListCommand, notificationsRosterRemoveCommand, notificationsSubscriptionsAddCommand, notificationsSubscriptionsListCommand, notificationsSubscriptionsRemoveCommand } from "./notifications.js";
-export { approveCommand, compileCommand, diagnosticsCommand, docsCommand, docsLlmCommand, doctorCommand, drainWorkerCommand, endpointsCommand, fixtureCommand, hookInstallCommand, initCommand, localAttachCommand, localDetachCommand, localDownCommand, localLogsCommand, localStatusCommand, localTrustRootCommand, localUpCommand, loginCommand, logoutCommand, notificationsChannelsAddCommand, notificationsChannelsListCommand, notificationsChannelsRemoveCommand, notificationsRosterAddCommand, notificationsRosterListCommand, notificationsRosterRemoveCommand, notificationsSubscriptionsAddCommand, notificationsSubscriptionsListCommand, notificationsSubscriptionsRemoveCommand, orchestratorsListCommand, orchestratorsUseCommand, orgCurrentCommand, orgListCommand, orgUseCommand, patCreateCommand, previewCommand, previewEvent, rejectCommand, runRemoteCommand, runRoutedCommand, runsArtifactsDownloadCommand, runsArtifactsListCommand, runsCancelCommand, runsListCommand, runsLogsCommand, runsRerunCommand, runsShowCommand, secretsListCommand, typesCommand, verifyAttestationCommand, watchCommand, workflowsListCommand };
+export { FEEDBACK_CONTRACT, approveCommand, compileCommand, diagnosticsCommand, docsCommand, docsLlmCommand, doctorCommand, drainWorkerCommand, endpointsCommand, feedbackCommand, fixtureCommand, hookInstallCommand, initCommand, localAttachCommand, localDetachCommand, localDownCommand, localLogsCommand, localStatusCommand, localTrustRootCommand, localUpCommand, loginCommand, logoutCommand, notificationsChannelsAddCommand, notificationsChannelsListCommand, notificationsChannelsRemoveCommand, notificationsRosterAddCommand, notificationsRosterListCommand, notificationsRosterRemoveCommand, notificationsSubscriptionsAddCommand, notificationsSubscriptionsListCommand, notificationsSubscriptionsRemoveCommand, orchestratorsListCommand, orchestratorsUseCommand, orgCurrentCommand, orgListCommand, orgUseCommand, patCreateCommand, previewCommand, previewEvent, rejectCommand, reportCommand, reportListCommand, reportWithdrawCommand, runRemoteCommand, runRoutedCommand, runsArtifactsDownloadCommand, runsArtifactsListCommand, runsCancelCommand, runsListCommand, runsLogsCommand, runsRerunCommand, runsShowCommand, secretsListCommand, typesCommand, verifyAttestationCommand, watchCommand, workflowsListCommand };

package/dist/commands/init.d.ts

@@ -19,8 +19,6 @@ export interface InitOptions {
     packageManager?: string;
     /** JavaScript-only mode (no TypeScript, no dependencies) */
     mjs?: boolean;
-    /** Write .npmrc pointing @kici-dev scope to local Verdaccio */
-    useVerdaccioLocal?: boolean;
     /** Private registry URL to scaffold a `registries:` entry for. */
     privateRegistry?: string;
     /** Optional npm scope (e.g. `@my-org`) the private registry serves. */
@@ -41,4 +39,13 @@ export interface InitOptions {
  * @returns true on success, false on error
  */
 export declare function initCommand(options?: InitOptions): Promise<boolean>;
+/**
+ * Scaffold `.kici/.gitignore` so the generated `types/` declarations stay
+ * untracked. Never overwrites an existing file — the customer may have edited
+ * it. Deliberately ignores only `types/`, NOT `kici.lock.json` (the
+ * orchestrator fetches the lock from the repo, so it genuinely is source).
+ *
+ * @param kiciDir - The resolved `.kici` directory path.
+ */
+export declare function writeKiciGitignore(kiciDir: string): Promise<void>;
 //# sourceMappingURL=init.d.ts.map