@kici-dev/compiler 0.7.0 → 0.9.0

package/dist/llm-context/llms-getting-started.txt

@@ -588,7 +588,7 @@ Point to a local SDK checkout for IDE autocompletion:
 {
   "name": "my-project-kici",
   "devDependencies": {
-    "@kici-dev/sdk": ">=0.0.1-0"
+    "@kici-dev/sdk": "latest"
   },
   "kici": {
     "sdkPath": "../../packages/sdk"
@@ -600,7 +600,7 @@ The `sdkPath` field tells the compiler where to resolve TypeScript path mappings
 
 ### KICI_DEV environment variable
 
-Set `KICI_DEV=true` to use a prerelease-compatible version range (`>=0.0.1-0`) in generated files, which resolves prerelease builds from a local Verdaccio registry:
+Set `KICI_DEV=true` to pin the SDK to the `latest` dist-tag in generated files, which resolves prerelease builds from a local Verdaccio registry:
 
 ```bash
 KICI_DEV=true npx kici init
@@ -845,7 +845,7 @@ Each guide is split into two parts. **Part 1** gets you a green run against your
 
 ## Bring a coding agent
 
-Workflows are TypeScript, so a coding agent can write them. KiCI ships its docs in a form an agent reads directly: point yours at [llms.txt](https://kici.dev/docs/llms.txt), or pipe a task bundle straight into its context with `kici docs llm` (`kici docs llm sdk` for the authoring API, `kici docs llm patterns` for recipes). An agent briefed that way can scaffold your first workflow, compile it, and read the failure when it breaks.
+Workflows are TypeScript, so a coding agent can write them. KiCI ships its docs in a form an agent reads directly: point yours at [llms.txt](https://kici.dev/llms.txt), or pipe a task bundle straight into its context with `kici docs llm` (`kici docs llm sdk` for the authoring API, `kici docs llm patterns` for recipes). An agent briefed that way can scaffold your first workflow, compile it, and read the failure when it breaks.
 
 If your agent finds that these docs promise something KiCI does not do, that is worth telling us — `kici feedback` prints how to report it, and [Reporting a discrepancy](https://docs.kici.dev/user/reporting-discrepancies/) is the full guide.
 
@@ -891,8 +891,10 @@ promised. You can report that.
 A human reader can use this page too. The rules below exist because the tracker
 is public and you are filing under someone else's GitHub identity.
 
-Run `kici feedback` to print this contract in your terminal, or
-`kici feedback --json` to read it as structured data.
+Run `kici feedback` to print this contract in your terminal,
+`kici feedback --json` to read it as structured data, or
+`kici feedback --draft <file.json> --open` to turn a draft into the prefilled form
+and open it.
 
 ## The rule, in one sentence
 
@@ -967,19 +969,20 @@ approval rule.
 
 ## What the report must carry
 
-Five things. A report missing any of them cannot be acted on:
+A report missing any of these fields cannot be acted on:
 
 | Field                                 | What it holds                                                                                                        |
 | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
 | What the docs or CLI advertise        | The exact claim, quoted, plus its source: a docs URL or the command whose `--help` says it.                          |
 | What actually happened                | The real output or behaviour, quoted, with any error text.                                                           |
 | Minimal reproduction, including setup | Every step from an empty directory: the setup commands, a minimal synthetic workflow, and the exact command you ran. |
-| Version and environment               | Output of `kici --version`, plus Node version and OS.                                                                |
+| KiCI version                          | Output of `kici --version`.                                                                                          |
+| Environment                           | Node version and OS.                                                                                                 |
 | Why this is a discrepancy             | One or two sentences ruling out the likely misreads — why the docs cannot be read to match what you observed.        |
 
 The last field is the one agents skip, and it is the one that makes a report
 usable. "The docs say `--foo` exists and it does not" is a claim. "`--foo` is
-documented at <url>, and `kici bar --help` on 0.1.16 lists no such flag" is a
+documented at <url>, and `kici bar --help` on the version I ran lists no such flag" is a
 finding someone can act on in one pass.
 
 Include setup steps whenever your reproduction needed any. A reproduction that
@@ -988,22 +991,36 @@ starts from state a maintainer cannot recreate is not a reproduction.
 ## Filing it
 
 The tracker is [kici-dev/kici-public](https://github.com/kici-dev/kici-public),
-and the form is **Agent report**:
+and the form is **Agent report** (`agent_report.yml`). It is a GitHub issue
+form, which only the browser can submit — `gh issue create` cannot fill it.
+So you draft, and the person files.
 
-```bash
-kici feedback --open
+Write the draft as JSON, one key per field of the form (`kici feedback --json`
+lists them under `draftFields`):
+
+```json
+{
+  "title": "kici compile --check writes a lock file",
+  "advertised": "https://docs.kici.dev/user/cli-reference/ says: `kici compile --check` type-checks without writing a lock file.",
+  "observed": ".kici/kici.lock.json was written; mtime changed.",
+  "reproduction": "$ mkdir /tmp/repro && cd /tmp/repro\n$ kici init\n$ kici compile --check",
+  "version": "0.8.0",
+  "environment": "Node 24.13.0, Ubuntu 24.04",
+  "justification": "The sentence names --check as the no-write mode; no reading of it allows a write."
+}
 ```
 
-Draft the complete body first. Show it to the person you are working with —
-the whole body, not a summary of it. File only after they say yes:
+Then build the prefilled form:
 
 ```bash
-gh issue create --repo kici-dev/kici-public --template agent_report.yml
+kici feedback --draft draft.json --open
 ```
 
-The form asks you to confirm the report was drafted by an agent and reviewed by
-a person before filing. Answer honestly; it is what lets maintainers triage
-agent-filed reports as a group.
+The command prints the form URL with every field filled in and, with
+`--open`, opens it. It reaches no network and files nothing. Show the person
+you are working with the whole draft — not a summary of it. They open the
+URL, read the prefilled form, tick the review boxes, and submit. File only
+after they say yes.
 
 If they say no, that is the end of it. Do not re-file the same finding in
 another form, and do not open it as a question instead.

package/dist/llm-context/llms-providers.txt

@@ -758,8 +758,8 @@ kici-admin org-settings global-workflows deny-add \
 ```
 
 See [Global workflows](https://docs.kici.dev/architecture/global-workflows/) for the
-policy model (`isWorkflowRepoAllowed` + `isSourceRepoAllowed` +
-`isElevatedAccessAllowed`) and the cross-provider dispatch contract.
+policy model (`isWorkflowRepoAllowed` + `isSourceRepoAllowed`) and the
+cross-provider dispatch contract.
 
 ## Routing-key collisions
 

package/dist/llm-context/llms-sdk-runtime.txt

@@ -1332,6 +1332,17 @@ interface StepContext<TInputs = Record<string, unknown>> {
   provider?: string;
   /** Whether this execution was triggered by `kici run remote` (developer-initiated remote run) */
   isTestRun: boolean;
+  /** The job's own checked-out repository (present for every job that checks out); `withWrite` opens a write window for it — see [Git credentials](https://docs.kici.dev/user/patterns/git-credentials/) */
+  repo?: {
+    identifier: string;
+    path: string;
+    ref?: string;
+    sha?: string;
+    withWrite(
+      opts: { permissions?: Record<string, string>; credential?: string },
+      fn: () => Promise<void>,
+    ): Promise<void>;
+  };
   /** Registering repo of a global workflow (undefined for non-global workflows) */
   workflowRepo?: RepoInfo;
   /** Repo where the triggering event occurred (undefined for non-global workflows) */
@@ -1532,13 +1543,15 @@ const deploy = job('deploy', {
 
 Request a short-lived OIDC ID token for the current job, bound to an `audience`. The token is a signed JWT whose identity claims (`repository`, `ref`, `sha`, `kici_run_id`, `kici_job_id`) are derived by your orchestrator from the run context — a step cannot spoof them. Use it to authenticate the build to an external service that trusts the orchestrator's OIDC issuer (for example, when generating build provenance).
 
-The token also carries the event context a cloud trust policy needs to tell a fork pull request from a trusted push — `is_fork`, `head_repository`, `trust_tier`, `event_name`, and a pull-request-specific `sub`. See [ID-token claims and cloud trust policies](https://docs.kici.dev/user/provenance/#id-token-claims-and-cloud-trust-policies) for the full claim table and a worked AWS policy.
+The token also carries the event context a cloud trust policy needs to tell a fork pull request from a trusted push — `is_fork`, `head_repository`, `trust_tier`, `event_name`, and a pull-request-specific `sub`. See [ID-token claims and cloud trust policies](https://docs.kici.dev/user/oidc/#id-token-claims-and-cloud-trust-policies) for the full claim table and a worked AWS policy.
 
 ```typescript
 const publish = job('publish', {
   steps: [
     step('mint', async (ctx) => {
-      const { token, expiresIn } = await ctx.kici.oidc.token({ audience: 'sigstore' });
+      const minted = await ctx.kici.oidc.token({ audience: 'sigstore' });
+      if ('deferred' in minted) throw new Error(`ID token deferred: ${minted.code}`);
+      const { token, expiresIn } = minted;
       ctx.log.info(`Got an ID token valid for ${expiresIn}s`);
       // Hand `token` to a tool that exchanges it with the trusting service.
     }),
@@ -1548,6 +1561,7 @@ const publish = job('publish', {
 
 **Behavior:**
 
+- The result is the minted token, or `{ deferred: true, code }` (`unavailable` | `failed`) when the orchestrator could not mint one right now. A step that exchanges the token fails on `deferred`; `ctx.attestProvenance` handles it by freezing the statement for later fulfilment.
 - The token is short-lived (about 10 minutes) and scoped to the current run and job.
 - The returned token value is automatically masked in step logs.
 - The step never holds signing credentials — the orchestrator mints and signs the token on the step's behalf from its own run records.

package/dist/llm-context/llms-sdk.txt

@@ -1051,9 +1051,8 @@ The throw is a `ChangedFilesUnavailableError` (exported from `@kici-dev/sdk`, ca
 ### evaluateRules(rules, context, label, onRuleResult?)
 
 The agent calls this on your behalf. A workflow does not call it. It lives on
-`@kici-dev/sdk/internal`, outside semver, and stays exported from the root barrel as
-`@deprecated` until v1.0.0 — see [deprecations](https://docs.kici.dev/user/deprecations/). It is described here
-because its return shape is what a rule's outcome looks like in the run log.
+`@kici-dev/sdk/internal`, outside semver, and is not exported from the root barrel. It is
+described here because its return shape is what a rule's outcome looks like in the run log.
 
 Evaluate an array of rules sequentially with fail-fast behavior. Stops on the first failure.
 
@@ -1306,9 +1305,8 @@ isDynamicFunction(matrix); // true if async function
 ### Matrix expansion utilities
 
 The agent expands a matrix for you. A workflow does not call these. They live on
-`@kici-dev/sdk/internal`, outside semver, and stay exported from the root barrel as
-`@deprecated` until v1.0.0 — see [deprecations](https://docs.kici.dev/user/deprecations/). They are described
-here because they define the combinations a matrix job actually produces.
+`@kici-dev/sdk/internal`, outside semver, and are not exported from the root barrel. They are
+described here because they define the combinations a matrix job actually produces.
 
 ```typescript
 import { expandMatrix, applyIncludeExclude } from '@kici-dev/sdk/internal';
@@ -1905,7 +1903,7 @@ Create a commit status trigger. Returns a frozen `StatusTriggerConfig`.
 function status(config?: StatusConfigInput): StatusTriggerConfig;
 ```
 
-**Config options:** `contexts` (picomatch strings like 'ci/\*'), `states` (error/failure/pending/success), `description`
+**Config options:** `contexts` (glob patterns like 'ci/\*'), `states` (error/failure/pending/success), `description`
 
 ```typescript
 status(); // Any status
@@ -2531,11 +2529,8 @@ a `.result` proxy reads, build the step context your workflow body receives, eva
 rules, and expand its matrix. The agent drives all of it on your behalf.
 
 It is **not covered by semver** and may change shape in any release. Do not import it from
-a workflow. Everything a workflow author needs is on the root entry point above.
-
-Those same symbols are also still exported from the root barrel, marked `@deprecated`, so
-an older SDK in a repository keeps working. They are removed from the root at v1.0.0 — see
-[deprecations](https://docs.kici.dev/user/deprecations/).
+a workflow. Everything a workflow author needs is on the root entry point above, and none
+of the runtime contract is exported there.
 
 ## See also
 

package/dist/llm-context/llms.txt

@@ -1,6 +1,6 @@
 # KiCI
 
-> KiCI is a TypeScript-native CI/CD workflow engine. Workflows are defined in TypeScript (not YAML), compiled into a portable lock file, and executed by self-hosted agents. The docs below cover the SDK, the CLI, workflow patterns, and the runtime architecture an LLM coding agent needs in order to author and test KiCI workflows.
+> KiCI is a TypeScript-native CI/CD workflow engine. Workflows are defined in TypeScript (not YAML), compiled into a portable lock file, and executed by self-hosted agents. The docs below cover the SDK, the CLI, workflow patterns, and the runtime architecture an LLM coding agent needs to author and test KiCI workflows.
 
 The full markdown bundle of every page indexed here is available at https://docs.kici.dev/llms-full.txt.
 
@@ -10,16 +10,16 @@ Found a mismatch between what these docs advertise and what KiCI does? Read http
 
 Each bundle below is a self-contained markdown file for one authoring task. Fetch only the one your task needs instead of the full bundle:
 
-- [getting-started](https://docs.kici.dev/llms-getting-started.txt) (65 KB) — Adopt KiCI: why it exists, how workflows execute, migrating from GitHub Actions, installing the SDK, and writing/compiling/testing your first workflow
+- [getting-started](https://docs.kici.dev/llms-getting-started.txt) (66 KB) — Adopt KiCI: why it exists, how workflows execute, migrating from GitHub Actions, installing the SDK, and writing/compiling/testing your first workflow
 - [patterns](https://docs.kici.dev/llms-patterns.txt) (61 KB) — Copy-paste workflow recipes: triggers, conditionals, matrix, scheduling, integrations
 - [sdk](https://docs.kici.dev/llms-sdk.txt) (131 KB) — Core authoring API: workflow/job/step factories, triggers, rules, matrix, dynamic jobs, cross-job outputs
-- [sdk-runtime](https://docs.kici.dev/llms-sdk-runtime.txt) (115 KB) — Runtime and advanced authoring: step runtime context, event payloads, host fan-out, idempotent steps, caching, artifacts, waiting
+- [sdk-runtime](https://docs.kici.dev/llms-sdk-runtime.txt) (116 KB) — Runtime and advanced authoring: step runtime context, event payloads, host fan-out, idempotent steps, caching, artifacts, waiting
 - [cli](https://docs.kici.dev/llms-cli.txt) (97 KB) — Running the CLI locally: compile, test, run local, hooks, lock-file drift, common failures
-- [cli-remote](https://docs.kici.dev/llms-cli-remote.txt) (109 KB) — Auth, org and orchestrator selection, runs, approvals, notifications, diagnostics, and the MCP server a coding agent connects to
-- [features](https://docs.kici.dev/llms-features.txt) (97 KB) — Deployment contexts, scoped secrets, private registries, approvals, provenance, dashboard and account access
+- [cli-remote](https://docs.kici.dev/llms-cli-remote.txt) (111 KB) — Auth, org and orchestrator selection, runs, approvals, notifications, diagnostics, and the MCP server a coding agent connects to
+- [features](https://docs.kici.dev/llms-features.txt) (112 KB) — Deployment contexts, scoped secrets, private registries, approvals, workload identity, provenance, dashboard and account access
 - [features-execution](https://docs.kici.dev/llms-features-execution.txt) (124 KB) — Concurrency, dynamic values, events, container jobs, environment variables, global workflows, idempotent steps
 - [providers](https://docs.kici.dev/llms-providers.txt) (35 KB) — Connecting sources: GitHub App, universal-git (Forgejo/Gitea/GitLab), local file://
-- [architecture](https://docs.kici.dev/llms-architecture.txt) (100 KB) — How the runtime works: three-tier relay model, data flows, configuration
+- [architecture](https://docs.kici.dev/llms-architecture.txt) (101 KB) — How the runtime works: three-tier relay model, data flows, configuration
 
 ## Getting started
 
@@ -86,6 +86,7 @@ Each bundle below is a self-contained markdown file for one authoring task. Fetc
 - [Approval gates](https://docs.kici.dev/user/approvals/): Pause a workflow for human sign-off at step, job, or workflow granularity with approval
 - [Contexts](https://docs.kici.dev/user/contexts/): Configure deployment contexts with variables, secrets, and protection rules
 - [Dashboard](https://docs.kici.dev/user/dashboard/): Web UI for monitoring workflow runs, managing sources, secrets, and organization settings.
+- [Workload identity with OIDC](https://docs.kici.dev/user/oidc/): Mint short-lived OIDC identity tokens in a step and exchange them with Cloudsmith, AWS, or any service that federates with your orchestrator
 - [Private npm registries](https://docs.kici.dev/user/private-registries/): Authenticate `npm install` against private registries (CodeArtifact, GitHub Packages, Verdaccio, …) from a workflow's `.kici/package.json`
 - [Build provenance and attestations](https://docs.kici.dev/user/provenance/): Generate and verify signed SLSA provenance for the artifacts your workflows build
 - [Secrets](https://docs.kici.dev/user/secrets/): How to access secrets in KiCI workflow steps

package/dist/local-plane/orchestrator-process.d.ts

@@ -26,15 +26,14 @@ export interface SpawnOrchestratorOptions {
      * generated by the plane. Enables the orchestrator's local OIDC mint +
      * dev-signed provenance (issuer `kici-local`) in independent mode. Present in
      * the independent boot; omitted (with `attach`) in the hybrid boot, which
-     * mints via the Platform relay instead.
+     * mints with the orchestrator's own signing key instead.
      */
     devIdentityKeyFile?: string;
     /**
      * When present, boot the orchestrator in HYBRID mode attached to the Platform
-     * relay instead of independent mode. OIDC + attestation then mint via the
-     * Platform (the local dev signer is never consulted — the orchestrator's
-     * `selectOidcMintRegistration` prefers the relay whenever a Platform
-     * connection exists).
+     * relay instead of independent mode. OIDC + attestation then mint with the
+     * orchestrator's own signing key under its own issuer, exactly as a deployed
+     * orchestrator does (the local dev signer is never consulted).
      */
     attach?: {
         /** Orchestrator KICI_PLATFORM_URL — a ws(s)://…/ws relay URL. */

package/dist/local-plane/orchestrator-process.js

@@ -1,5 +1,6 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { planePaths, planePorts } from "./paths.js";
+import { rotatePlaneLogIfOversized } from "./plane-log.js";
 import { createRequire } from "node:module";
 import fs from "node:fs";
 import { spawn } from "node:child_process";
@@ -48,6 +49,7 @@ function spawnOrchestratorProcess(databaseUrl, opts) {
 	const { logFile, root, cacheDir } = planePaths();
 	fs.mkdirSync(root, { recursive: true });
 	fs.mkdirSync(cacheDir, { recursive: true });
+	rotatePlaneLogIfOversized(logFile);
 	const out = fs.openSync(logFile, "a");
 	const baseEnv = {};
 	for (const [key, value] of Object.entries(process.env)) if (!key.startsWith("KICI_")) baseEnv[key] = value;
@@ -58,6 +60,7 @@ function spawnOrchestratorProcess(databaseUrl, opts) {
 		KICI_AGENT_AUTH: "none",
 		KICI_HOST: "127.0.0.1",
 		KICI_AUTO_MIGRATE: "true",
+		KICI_CLUSTER_SINGLE_NODE: "true",
 		KICI_DATA_DIR: root,
 		KICI_BOOTSTRAP_ADMIN_TOKEN: opts.adminToken,
 		KICI_SECRET_KEY: opts.secretKey,
@@ -74,7 +77,8 @@ function spawnOrchestratorProcess(databaseUrl, opts) {
 		modeEnv = {
 			KICI_MODE: "hybrid",
 			KICI_PLATFORM_URL: opts.attach.platformWsUrl,
-			KICI_PLATFORM_TOKEN: opts.attach.platformToken
+			KICI_PLATFORM_TOKEN: opts.attach.platformToken,
+			KICI_ORCHESTRATOR_PROVENANCE_ISSUER: `http://127.0.0.1:${port}`
 		};
 	} else {
 		entry = resolveStandaloneEntry();

package/dist/local-plane/paths.d.ts

@@ -33,6 +33,7 @@ export declare function planePaths(): {
     pidfile: string;
     stampFile: string;
     logFile: string;
+    pgLogFile: string;
     socketDir: string;
     adminTokenFile: string;
     platformTokenFile: string;

package/dist/local-plane/paths.js

@@ -48,6 +48,7 @@ function planePaths() {
 		pidfile: path.join(root, "plane.pid"),
 		stampFile: path.join(root, "stamp.json"),
 		logFile: path.join(root, "orchestrator.log"),
+		pgLogFile: path.join(root, "orchestrator.log.pg"),
 		socketDir: path.join(root, "sock"),
 		adminTokenFile: path.join(root, "admin-token"),
 		platformTokenFile: path.join(root, "platform-token"),

package/dist/local-plane/plane-log.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Size at which a local dev plane log is rotated on the next plane start.
+ *
+ * The plane's orchestrator writes one JSON line per request and per
+ * scheduled-job tick, and nothing truncates the file between boots, so an
+ * unrotated log grows without bound. 50 MB is roughly 200k lines — more history
+ * than a local debugging session reads.
+ */
+export declare const PLANE_LOG_MAX_BYTES: number;
+/** The cap expressed in whole megabytes, for the messages that name it. */
+export declare const PLANE_LOG_MAX_MB: number;
+/**
+ * Rotate `file` to `<file>.1` once it reaches `PLANE_LOG_MAX_BYTES`, keeping two
+ * generations: any previous `.1` is discarded.
+ *
+ * Call this only where nothing holds the file open. A rename under a live
+ * writer leaves that writer appending to the renamed inode, so the live log
+ * would stay empty for the rest of the process's life.
+ *
+ * Every failure is swallowed on purpose. Both callers are on a plane-boot path:
+ * `startPlanePostgres` reads a throw as "embedded Postgres is unavailable" and
+ * silently falls back to a Podman container, and `spawnOrchestratorProcess`
+ * would fail the boot outright. A log that cannot be rotated must not cost the
+ * user their plane.
+ */
+export declare function rotatePlaneLogIfOversized(file: string): void;
+//# sourceMappingURL=plane-log.d.ts.map

package/dist/local-plane/plane-log.js

@@ -0,0 +1,39 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import fs from "node:fs";
+//#region src/local-plane/plane-log.ts
+/**
+* Size at which a local dev plane log is rotated on the next plane start.
+*
+* The plane's orchestrator writes one JSON line per request and per
+* scheduled-job tick, and nothing truncates the file between boots, so an
+* unrotated log grows without bound. 50 MB is roughly 200k lines — more history
+* than a local debugging session reads.
+*/
+const PLANE_LOG_MAX_BYTES = 52428800;
+/** The cap expressed in whole megabytes, for the messages that name it. */
+const PLANE_LOG_MAX_MB = PLANE_LOG_MAX_BYTES / 1048576;
+/**
+* Rotate `file` to `<file>.1` once it reaches `PLANE_LOG_MAX_BYTES`, keeping two
+* generations: any previous `.1` is discarded.
+*
+* Call this only where nothing holds the file open. A rename under a live
+* writer leaves that writer appending to the renamed inode, so the live log
+* would stay empty for the rest of the process's life.
+*
+* Every failure is swallowed on purpose. Both callers are on a plane-boot path:
+* `startPlanePostgres` reads a throw as "embedded Postgres is unavailable" and
+* silently falls back to a Podman container, and `spawnOrchestratorProcess`
+* would fail the boot outright. A log that cannot be rotated must not cost the
+* user their plane.
+*/
+function rotatePlaneLogIfOversized(file) {
+	try {
+		if (fs.statSync(file).size < 52428800) return;
+		fs.rmSync(`${file}.1`, { force: true });
+		fs.renameSync(file, `${file}.1`);
+	} catch {}
+}
+//#endregion
+export { PLANE_LOG_MAX_BYTES, PLANE_LOG_MAX_MB, rotatePlaneLogIfOversized };
+
+//# sourceMappingURL=plane-log.js.map

package/dist/local-plane/plane-manager.js

@@ -19,8 +19,8 @@ import { generateKeyPairSync, randomBytes } from "node:crypto";
 */
 function currentBuildIdentity() {
 	return {
-		version: "0.7.0",
-		buildCommit: "31843a21c"
+		version: "0.9.0",
+		buildCommit: "69765a7ee"
 	};
 }
 /**

package/dist/local-plane/plane-trigger.d.ts

@@ -11,6 +11,9 @@
  * The source's bundle hot-reload is debounced, so a first trigger can land
  * before the plane has registered the (re-pointed) local source. This resends
  * the webhook after a grace window until a run appears or the timeout elapses.
+ * When the budget still runs out, the timeout is explained rather than merely
+ * reported: the plane's own Raft role and its event-log record for this
+ * delivery decide which cause is named.
  */
 /** A minimal admin-read client (AdminApiClient.get) — injectable for tests. */
 export interface RunDiscoveryClient {
@@ -58,7 +61,32 @@ export interface TriggerRunOptions {
     pollIntervalMs?: number;
     resendAfterMs?: number;
     timeoutMs?: number;
+    /** Workdir the plane's local source points at — named in the lock-file diagnosis. */
+    repoBasePath?: string;
+    /** Plane log path — named when nothing else explains the timeout. */
+    logPath?: string;
 }
+/** What the diagnosis knows about the trigger that just timed out. */
+export interface TriggerTimeoutContext {
+    /** Routing-key-scoped delivery id, or null when the plane never accepted the webhook. */
+    deliveryId: string | null;
+    orgId: string;
+    /** Commit the synthetic push carried (the workdir's overlay commit). */
+    sha: string;
+    /** Absolute path the plane's local source points at — the run's workdir. */
+    repoBasePath?: string;
+    /** Plane log path, named in the fallback so the developer has somewhere to look. */
+    logPath?: string;
+}
+/**
+ * Explain a trigger timeout in one line, from what the plane itself recorded.
+ *
+ * Ordered most-specific-first, and every branch is a fact read back off the
+ * plane rather than an inference: the Raft role it reports, then the status it
+ * wrote for THIS delivery, then the delivery id + log path so the developer has
+ * a thread to pull even when neither surface answered.
+ */
+export declare function diagnoseTriggerTimeout(client: RunDiscoveryClient, ctx: TriggerTimeoutContext): Promise<string>;
 /**
  * Trigger the run and resolve its runId. Sends the synthetic push, then polls
  * the admin runs list filtered by this webhook's routing-key-scoped delivery id

package/dist/local-plane/plane-trigger.js

@@ -1,4 +1,5 @@
 import "../rolldown-runtime-ClRpJifh.js";
+import { EventLogStatus } from "@kici-dev/engine";
 import { randomUUID } from "node:crypto";
 import { AdminApiClient } from "@kici-dev/orchestrator";
 //#region src/local-plane/plane-trigger.ts
@@ -15,6 +16,9 @@ import { AdminApiClient } from "@kici-dev/orchestrator";
 * The source's bundle hot-reload is debounced, so a first trigger can land
 * before the plane has registered the (re-pointed) local source. This resends
 * the webhook after a grace window until a run appears or the timeout elapses.
+* When the budget still runs out, the timeout is explained rather than merely
+* reported: the plane's own Raft role and its event-log record for this
+* delivery decide which cause is named.
 */
 /**
 * Build the GitHub-shaped webhook request the plane's local provider normalizer
@@ -62,6 +66,50 @@ async function sendLocalTrigger(planeUrl, req) {
 		deliveryId
 	};
 }
+/** Raft role the plane reports, or null when `/cluster/health` cannot be read. */
+async function readPlaneRole(client) {
+	try {
+		const health = await client.get("/cluster/health");
+		return typeof health.role === "string" ? health.role : null;
+	} catch {
+		return null;
+	}
+}
+/** The plane's own record of this delivery, or null when there is none to read. */
+async function readDelivery(client, orgId, deliveryId) {
+	try {
+		const qs = new URLSearchParams({
+			deliveryId,
+			orgId,
+			limit: "1"
+		});
+		return (await client.get(`/api/v1/admin/event-log?${qs}`)).deliveries?.[0] ?? null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Explain a trigger timeout in one line, from what the plane itself recorded.
+*
+* Ordered most-specific-first, and every branch is a fact read back off the
+* plane rather than an inference: the Raft role it reports, then the status it
+* wrote for THIS delivery, then the delivery id + log path so the developer has
+* a thread to pull even when neither surface answered.
+*/
+async function diagnoseTriggerTimeout(client, ctx) {
+	const role = await readPlaneRole(client);
+	if (role !== null && role !== "leader") return `plane is not leader yet (election grace period) — it reports Raft role "${role}". A single-node plane should elect itself within seconds; check ${ctx.logPath ?? "the plane log (`kici local logs`)"} for "self-electing as leader".`;
+	const delivery = ctx.deliveryId ? await readDelivery(client, ctx.orgId, ctx.deliveryId) : null;
+	if (delivery?.status === EventLogStatus.enum.lockfile_missing) {
+		const where = ctx.repoBasePath ? ` in ${ctx.repoBasePath}` : "";
+		return `no kici.lock.json at ${ctx.sha}${where} — the plane resolved no lock file for this commit, so nothing matched. Make sure .kici/kici.lock.json is committed or present in the working tree the run packs.`;
+	}
+	if (delivery?.status) {
+		const detail = delivery.errorMessage ? ` (${delivery.errorMessage})` : "";
+		return `the plane recorded delivery ${ctx.deliveryId} as "${delivery.status}"${detail} but created no run.`;
+	}
+	return `no run appeared for ${ctx.deliveryId ? `delivery ${ctx.deliveryId}` : "this trigger — the plane never accepted the webhook (no delivery id came back)"}${ctx.logPath ? ` — see ${ctx.logPath}` : ""}`;
+}
 /**
 * Trigger the run and resolve its runId. Sends the synthetic push, then polls
 * the admin runs list filtered by this webhook's routing-key-scoped delivery id
@@ -90,7 +138,14 @@ async function triggerRun(planeUrl, adminToken, input, opts = {}) {
 		}
 		await sleep(pollIntervalMs);
 	}
-	throw new Error("offline run: no run appeared after triggering the local plane");
+	const cause = await diagnoseTriggerTimeout(client, {
+		deliveryId,
+		orgId: input.orgId,
+		sha: input.sha,
+		...opts.repoBasePath !== void 0 && { repoBasePath: opts.repoBasePath },
+		...opts.logPath !== void 0 && { logPath: opts.logPath }
+	});
+	throw new Error(`offline run: ${cause}`);
 }
 /** Return the run created by this webhook delivery, or null when none yet. */
 async function findRunByDelivery(client, deliveryId) {
@@ -105,6 +160,6 @@ function sleep(ms) {
 	return new Promise((r) => setTimeout(r, ms));
 }
 //#endregion
-export { buildLocalTriggerRequest, sendLocalTrigger, triggerRun };
+export { buildLocalTriggerRequest, diagnoseTriggerTimeout, sendLocalTrigger, triggerRun };
 
 //# sourceMappingURL=plane-trigger.js.map

package/dist/local-plane/postgres.js

@@ -1,5 +1,6 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { planePaths, planePorts } from "./paths.js";
+import { rotatePlaneLogIfOversized } from "./plane-log.js";
 import { createRequire } from "node:module";
 import path from "node:path";
 import fs from "node:fs";
@@ -104,14 +105,13 @@ async function embeddedClusterIsServing(port) {
 /**
 * Start a detached embedded postmaster via `pg_ctl` so it survives the exit of
 * this CLI process (embedded-postgres's in-process server is killed by its own
-* exit hook, so it cannot back a warm plane). A cluster already serving this
-* plane's port is reused as-is.
+* exit hook, so it cannot back a warm plane). The caller decides whether a
+* cluster is already serving; this always starts one.
 */
 async function defaultEmbeddedDaemon(port) {
-	const { pgData, logFile } = planePaths();
-	if (await embeddedClusterIsServing(port)) return;
+	const { pgData, pgLogFile } = planePaths();
 	const pgCtl = resolvePgCtl();
-	await $`${pgCtl} -D ${pgData} -o ${`-p ${port}`} -l ${`${logFile}.pg`} -w start`.quiet();
+	await $`${pgCtl} -D ${pgData} -o ${`-p ${port}`} -l ${pgLogFile} -w start`.quiet();
 }
 /** Stop the detached embedded postmaster (handle-independent, reads the data dir). */
 async function stopEmbeddedDaemon() {
@@ -141,7 +141,10 @@ async function startPlanePostgres(opts = {}) {
 	const url = `postgres://kici:kici@127.0.0.1:${port}/kici_local`;
 	if (!(opts.forcePodman || process.env.KICI_LOCAL_PG_MODE === "podman")) try {
 		await ensureEmbeddedCluster(port);
-		await embeddedDaemon(port);
+		if (!await embeddedClusterIsServing(port)) {
+			rotatePlaneLogIfOversized(planePaths().pgLogFile);
+			await embeddedDaemon(port);
+		}
 		return {
 			url,
 			kind: "embedded",

package/dist/local-plane/run-follow.js

@@ -1,4 +1,5 @@
 import "../rolldown-runtime-ClRpJifh.js";
+import { unwrapStoredLogLine } from "../remote/output/streaming.js";
 import { ExecutionJobStatus, ExecutionRunStatus, TERMINAL_JOB_STATES, TERMINAL_RUN_STATES } from "@kici-dev/engine";
 import { AdminApiClient } from "@kici-dev/orchestrator";
 //#region src/local-plane/run-follow.ts
@@ -131,7 +132,7 @@ async function drainLogs(client, runId, cursors, onLine) {
 				const qs = cursor ? `?cursor=${encodeURIComponent(cursor)}` : "";
 				const page = await client.get(`/api/v1/admin/runs/${runId}/jobs/${job.jobId}/steps/${step.stepIndex}/logs${qs}`);
 				for (const l of page.lines) {
-					onLine(l.value);
+					onLine(unwrapStoredLogLine(l.value));
 					emitted++;
 				}
 				cursor = page.nextCursor ?? String(page.totalLines);

package/dist/remote/output/streaming.d.ts

@@ -7,6 +7,18 @@
  * - Prints step transition headers
  * - Tracks elapsed time with in-place status updates
  */
+/**
+ * The text a stored log line carries.
+ *
+ * The orchestrator stores every step log line as a JSON envelope —
+ * `{"ts":…,"level":"stdout","msg":"…","meta":{}}` — and the Platform relay
+ * returns those envelopes verbatim, so a run's log stream is the envelope
+ * stream. The dashboard unwraps `msg` before rendering; the terminal must too,
+ * or the developer watching `kici run remote` reads raw JSON. A line that is
+ * not an envelope (an orchestrator phase marker, a plain line from an older
+ * store) passes through unchanged.
+ */
+export declare function unwrapStoredLogLine(line: string): string;
 export declare class StreamingFormatter {
     /** Color assignment per job name. */
     private readonly jobColors;