@kici-dev/compiler 0.5.0 → 0.6.1

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

@@ -109,7 +109,7 @@ An orchestrator enforces a few limits, each surfaced as a clear step error when
 - A **per-org storage quota** (20 GiB by default) across all non-expired artifacts.
 - An **expiry** (30 days by default) after which an artifact is no longer downloadable or listed.
 
-Operators can raise or lower the quota and expiry per organization; see the [orchestrator storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/#artifacts) for the operator-facing knobs.
+Each of the four is a cluster-wide default an operator can raise or lower per organization; see the [orchestrator storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/#artifacts) for the operator-facing knobs.
 
 When an upload or download fails for a reason that is **not** one of these limits — the orchestrator has no artifact storage configured, or it could not service the request — the step error says exactly that, instead of reporting a quota rejection or a missing artifact. So an error that names a limit really is a limit you can act on, and an error that names an orchestrator problem is one to take to whoever runs it.
 
@@ -266,7 +266,7 @@ Source: https://docs.kici.dev/user/sdk/event-payloads/
 
 ## The envelope
 
-The normalized event envelope is the single event contract in KiCI. Rules receive it as `ctx.event`, and every dynamic function — `environment:`, `env:`, and `concurrencyGroup:` resolvers, generated jobs, and a workflow's `concurrency.group` — receives the same envelope as its argument.
+The normalized event envelope is the single event contract in KiCI. Rules receive it as `ctx.event`, and every dynamic function — `context:`, `env:`, and `concurrencyGroup:` resolvers, generated jobs, and a workflow's `concurrency.group` — receives the same envelope as its argument.
 
 Narrow on the `type` field to branch per trigger kind (`if (event.type === 'push')`). The raw provider webhook body is nested at `payload`; the typed variants below describe its shape per event type.
 
@@ -712,7 +712,7 @@ export const setup = job('setup', {
 
 ## `checkStep(name, options)`
 
-The check-mode-aware sibling of `idempotentStep()`. It takes the **same option shape**, but behaves differently when a run is started in check mode (`kici run --check`):
+The check-mode-aware sibling of `idempotentStep()`. It takes a closely related option shape, but behaves differently when a run is started in check mode (`kici run --check`):
 
 | Factory          | Behavior under `kici run --check`         |
 | ---------------- | ----------------------------------------- |
@@ -730,10 +730,16 @@ Use `checkStep()` for deploy-style steps where you want a dry-run preview of pen
 | `apply`           | `(ctx, drift: TDrift) => Promise<TApplied>` | Yes      | Brings the system to the desired state. Runs only in apply mode (skipped under `kici run --check`). |
 | `summarize`       | `(drift: TDrift) => string`                 | Yes      | Human-readable summary of what `apply()` would do; shown in check-mode drift output.                |
 | `whenInSync`      | `(ctx) => Promise<TInSync>`                 | No       | Runs when `check()` returned `null` (already in sync).                                              |
+| `outputs`         | `OutputSchema`                              | No       | Zod schema validating the step's outputs at runtime.                                                |
 | `continueOnError` | `boolean`                                   | No       | When true, the job proceeds even if this step fails.                                                |
 | `timeout`         | `number`                                    | No       | Step-level timeout in milliseconds.                                                                 |
+| `retry`           | `number \| RetryConfig`                     | No       | Retry policy for the step; `retry: N` is shorthand for `{ maxAttempts: N }`.                        |
+| `cache`           | `CacheInput`                                | No       | Declarative cache restored before the step and saved after it succeeds.                             |
+| `rules`           | `Rule[]`                                    | No       | Step-level conditional rules, evaluated agent-side.                                                 |
 
-The one signature difference from `idempotentStep`: `apply` and `whenInSync` receive `ctx` as their first argument, so the apply logic has access to `ctx.$`, `ctx.log`, and `ctx.secrets`.
+Everything from `outputs` down is a plain [`step()` option](https://docs.kici.dev/user/sdk/core/) forwarded to the underlying step. The three step options `checkStep` does **not** accept are `onCancel`, `cleanup`, and `approval`.
+
+There are two signature differences from `idempotentStep`. First, `apply` and `whenInSync` receive `ctx` as their first argument, so the apply logic has access to `ctx.$`, `ctx.log`, and `ctx.secrets`. Second, `summarize` is **required** here, because it is what check mode prints; `idempotentStep` defaults it to a JSON dump of the drift. `idempotentStep` also takes none of the step-option passthroughs above.
 
 ### Result
 
@@ -841,6 +847,21 @@ const patch = job('patch', {
 });
 ```
 
+### Which hosts are targets
+
+`runsOnAll` targets the hosts you declare as members of your fleet. A host becomes
+a target when it registers with the orchestrator under a stable agent identity, or
+when an operator declares it with `kici-admin host declare`.
+
+Agents that an auto-scaler starts are **not** targets, even when their labels match
+the predicate. An auto-scaler starts an agent at the fixed shape of its pool, so a
+pinned child would run at that shape and not at its own. Auto-scaler agents stay
+available to `runsOn` and to the queue, and `ctx.kici.inventory` continues to list
+them.
+
+The fleet preview and the host detail page in the web UI apply the same rule, so
+they show the hosts a run targets.
+
 ### Input forms
 
 `runsOnAll` accepts three shapes:

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

@@ -961,7 +961,7 @@ Source: https://docs.kici.dev/user/sdk/rules-matrix-dynamic/
 
 Rules control conditional execution of workflows and jobs. A rule that returns `false` (or whose check function returns `false`) prevents execution.
 
-A rule's check function that **returns `false`** cleanly skips the job or step. A check function that **throws** is treated as an evaluation failure, not a skip: the job or step **fails** with the error surfaced (both on a remote run and when running locally with `kici run --local`), so a broken rule can never silently pass as a green run. For example, `rule('main only', (ctx) => ctx.event.ref.endsWith('main'))` throws on an event whose `ref` is undefined — that run fails with the error instead of quietly skipping every step. Fix the thrown error (guard the access) rather than relying on the skip.
+A rule's check function that **returns `false`** cleanly skips the job or step. A check function that **throws** counts as an evaluation failure, not a skip. The job or step **fails** with the error surfaced (both on a remote run and when running locally with `kici run --local`), so a broken rule can never silently pass as a green run. For example, `rule('main only', (ctx) => ctx.event.ref.endsWith('main'))` throws on an event whose `ref` is undefined — that run fails with the error instead of quietly skipping every step. Fix the thrown error (guard the access) rather than relying on the skip.
 
 ### rule(label) / rule(label, check)
 
@@ -2435,6 +2435,36 @@ workflow('post-deploy', {
 
 The orchestrator automatically emits system events for workflow and job completions. You do not need to call `ctx.emit()` for these -- they are generated by the orchestrator after execution. Listen for them with `workflowComplete()` and `jobComplete()` triggers.
 
+### Event scaler events
+
+The [event scaler backend](https://docs.kici.dev/operator/orchestrator/event-scaler/) emits two reserved events that your provisioning and teardown workflows subscribe to. The SDK exports their names and payload schemas, so a workflow imports the contract instead of re-declaring it.
+
+| Export                   | What it is                                                                                                              |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `SCALER_EVENT_NAMES`     | The two reserved event names: `SCALER_EVENT_NAMES.scaleUp` and `SCALER_EVENT_NAMES.scaleDown`.                          |
+| `ScalerScaleUpPayload`   | Schema of the scale-up payload. `.parse(ctx.rawPayload)` returns the typed payload and rejects a malformed one.         |
+| `ScalerScaleDownPayload` | Schema of the scale-down payload, including the narrowed `reason`.                                                      |
+| `ScaleDownReason`        | Why the scaler asked for a teardown: `idle`, `job-complete`, `heartbeat-timeout`, `spawn-timeout`, `drain`, `shutdown`. |
+
+```ts
+import { workflow, job, kiciEvent, SCALER_EVENT_NAMES, ScalerScaleUpPayload } from '@kici-dev/sdk';
+
+export default workflow('provision', {
+  on: [kiciEvent({ name: SCALER_EVENT_NAMES.scaleUp, match: { '$.scalerName': 'hetzner' } })],
+  jobs: [
+    job('provision', {
+      runsOn: ['kici:os:linux'],
+      run: async (ctx) => {
+        const payload = ScalerScaleUpPayload.parse(ctx.rawPayload);
+        ctx.log.info(`provision agent ${payload.agentId}`);
+      },
+    }),
+  ],
+});
+```
+
+These names are reserved. `ctx.emit()` rejects any event name that starts with `kici.`, so a workflow step cannot forge a scaler event. For every payload field, see the [event contract reference](https://docs.kici.dev/operator/orchestrator/event-scaler-events/). For complete provisioning and teardown workflows, see [autoscaling workflows](https://docs.kici.dev/user/workflows/autoscaling-workflows/).
+
 ---
 
 ## SDK reference

package/dist/llm-context/llms.txt

@@ -4,32 +4,39 @@
 
 The full markdown bundle of every page indexed here is available at https://docs.kici.dev/llms-full.txt.
 
+Found a mismatch between what these docs advertise and what KiCI does? Read https://docs.kici.dev/user/reporting-discrepancies/ (or run `kici feedback`) before reporting it: a report needs a reproduction, and you draft it but a human decides to file it.
+
 ## Bundles
 
 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) (51 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) (50 KB) — Copy-paste workflow recipes: triggers, conditionals, matrix, scheduling, integrations
-- [sdk](https://docs.kici.dev/llms-sdk.txt) (125 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) (112 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) (187 KB) — Running the CLI: compile, test, run local/remote, auth, hooks, lock-file drift
-- [features](https://docs.kici.dev/llms-features.txt) (158 KB) — Workflow features: concurrency, contexts, secrets, approvals, provenance, events
-- [providers](https://docs.kici.dev/llms-providers.txt) (37 KB) — Connecting sources: GitHub App, universal-git (Forgejo/Gitea/GitLab), local file://
-- [architecture](https://docs.kici.dev/llms-architecture.txt) (95 KB) — How the runtime works: three-tier relay model, data flows, configuration
+- [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
+- [patterns](https://docs.kici.dev/llms-patterns.txt) (57 KB) — Copy-paste workflow recipes: triggers, conditionals, matrix, scheduling, integrations
+- [sdk](https://docs.kici.dev/llms-sdk.txt) (127 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) (114 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) (90 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) (106 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) (90 KB) — Deployment contexts, scoped secrets, private registries, approvals, provenance, dashboard and account access
+- [features-execution](https://docs.kici.dev/llms-features-execution.txt) (121 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) (99 KB) — How the runtime works: three-tier relay model, data flows, configuration
 
 ## Getting started
 
 - [User guide](https://docs.kici.dev/user/): Writing and testing CI/CD workflows in TypeScript, running on infrastructure you control
 - [How your workflow code executes](https://docs.kici.dev/user/execution-model/): When and where your workflow TypeScript runs — compile time, orchestrator time, and agent time
+- [Getting help](https://docs.kici.dev/user/getting-help/): How to report a problem to KiCI and send the diagnostic context privately
 - [Getting started with workflows](https://docs.kici.dev/user/getting-started/): Install the SDK, write your first workflow, compile and test locally
 - [Migrating from GitHub Actions](https://docs.kici.dev/user/migrating-from-github-actions/): Map GitHub Actions concepts to KiCI, translate a real workflow side-by-side, and see what has no equivalent yet
 - [5-minute quickstart](https://docs.kici.dev/user/quickstart/): Stand up a KiCI orchestrator + agent and run your first workflow
+- [Reporting a discrepancy](https://docs.kici.dev/user/reporting-discrepancies/): For coding agents — how to report a mismatch between what KiCI's docs advertise and what the tooling does, with the reproduction and the approval a report needs.
 - [Why KiCI](https://docs.kici.dev/user/why-kici/): The case for running CI on infrastructure you control, with typed TypeScript workflows you test locally
 
 ## Workflow patterns
 
 - [Basic workflow patterns](https://docs.kici.dev/user/patterns/basic/): Basic CI, PR-only / push-only filters, multiple triggers, manual-only workflows
 - [Conditionals & matrix patterns](https://docs.kici.dev/user/patterns/conditionals-matrix/): Conditional execution with rules, matrix builds (static + dynamic), dynamic job generation
+- [Git credentials](https://docs.kici.dev/user/patterns/git-credentials/): Authenticated git in a workflow — declaring credentials from the secrets backend, and pushing
 - [Host restart & wait-for-alive](https://docs.kici.dev/user/patterns/host-restart/): Reboot the host a workflow runs on and continue after it comes back
 - [Integration patterns](https://docs.kici.dev/user/patterns/integrations/): Workflow chaining, generic webhooks, Stripe, self-hosted git forges, plain GitHub repos
 - [Pattern reference](https://docs.kici.dev/user/patterns/reference/): Step context, examples repository, GitHub check run output — cross-cutting reference for all patterns
@@ -55,36 +62,44 @@ Each bundle below is a self-contained markdown file for one authoring task. Fetc
 - [SDK reference: temp directories](https://docs.kici.dev/user/sdk/temp-directories/): Allocate job-scoped scratch dirs and files with ctx.mktemp() / ctx.mktempFile()
 - [SDK reference: waitFor](https://docs.kici.dev/user/sdk/wait-for/): Polling helpers for steps that pause until an external condition becomes true
 
-## CLI and authoring
+## CLI: authoring on your own machine
 
-- [Drive KiCI from your coding agent](https://docs.kici.dev/user/ai-agents/): Point a coding agent at KiCI's MCP server and let it trigger, read, and re-run your CI under your own identity.
-- [CLI authentication](https://docs.kici.dev/user/cli-auth/): Authenticate the KiCI CLI with browser OAuth, device flow, or API key paste
-- [CLI reference](https://docs.kici.dev/user/cli-reference/): All CLI commands: compile, preview, local, fixture, types, workflows, hook, docs, run, runs, approve, reject, login, logout, init, org, pat, secrets, admin, orchestrators, endpoints, notifications, verify-attestation, diagnostics, doctor
+- [CLI reference](https://docs.kici.dev/user/cli-reference/): All CLI commands: compile, preview, local, fixture, types, workflows, hook, docs, run, runs, approve, reject, login, logout, init, org, pat, secrets, admin, orchestrators, endpoints, notifications, verify-attestation, diagnostics, doctor, report, feedback
 - [Common failures](https://docs.kici.dev/user/common-failures/): Symptom-to-fix reference for the failures workflow authors hit most — no jobs dispatched, lock-file drift, missing webhooks, and agents that won't connect
 - [Lifecycle hooks](https://docs.kici.dev/user/hooks/): SDK hook API for cancel, cleanup, success, failure, and step-level callbacks
 - [Lock file and workflow drift](https://docs.kici.dev/user/lock-file-and-drift/): Keep the lock file in sync with your workflow source and avoid drift
 - [Testing guide](https://docs.kici.dev/user/testing-guide/): Running remote test fixtures with kici run remote
 - [Workflow patterns](https://docs.kici.dev/user/workflow-patterns/): Common patterns: monorepo builds, conditional jobs, dynamic matrices, generic webhooks, scheduling
-- [kici: account & org](https://docs.kici.dev/user/cli/account-and-org/): Login, org selection, personal access tokens, secrets, and admin
 - [kici: authoring & local dev](https://docs.kici.dev/user/cli/authoring-and-local/): Compile, preview, local execution, fixtures, types, workflows, hooks, and docs
+
+## CLI: driving a deployed orchestrator
+
+- [Drive KiCI from your coding agent](https://docs.kici.dev/user/ai-agents/): Point a coding agent at KiCI's MCP server and let it trigger, read, and re-run your CI under your own identity.
+- [CLI authentication](https://docs.kici.dev/user/cli-auth/): Authenticate the KiCI CLI with browser OAuth, device flow, or API key paste
+- [kici: account & org](https://docs.kici.dev/user/cli/account-and-org/): Login, org selection, personal access tokens, secrets, and admin
 - [kici: notifications & diagnostics](https://docs.kici.dev/user/cli/notifications-and-diagnostics/): Notification channels, attestation verification, and diagnostics
 - [kici: runs & approvals](https://docs.kici.dev/user/cli/runs-and-approvals/): Run push and inspection plus approval / rejection of held runs
 
-## Workflow features
+## Workflow features: access and approval
 
 - [Account and sign-in](https://docs.kici.dev/user/account-and-login/): How your KiCI account relates to sign-in methods, and how to change the way you sign in.
 - [Approval gates](https://docs.kici.dev/user/approvals/): Pause a workflow for human sign-off at step, job, or workflow granularity with approval
-- [Concurrency groups](https://docs.kici.dev/user/concurrency/): Control parallel execution with auto-cancel and queue modes
 - [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.
+- [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
+
+## Workflow features: execution
+
+- [Concurrency groups](https://docs.kici.dev/user/concurrency/): Control parallel execution with auto-cancel and queue modes
+- [Container jobs](https://docs.kici.dev/user/container-jobs/): Run a job inside any container image, including a private one, without that image shipping Node or git
 - [Dynamic values](https://docs.kici.dev/user/dynamic-values/): Compute a job's context, env, and concurrencyGroup at runtime from the incoming event
 - [Environment variables](https://docs.kici.dev/user/env-vars/): Environment variable reference for the CLI
 - [Event system](https://docs.kici.dev/user/events/): How KiCI's event model works -- event types, the registration model, event matching, and circuit breaker protection
 - [Global workflows](https://docs.kici.dev/user/global-workflows/): Cross-repo workflows that run on events from any repo in the same org
 - [Idempotent steps and check mode](https://docs.kici.dev/user/idempotent-steps/): Declare desired state with a step check facet, then run in apply or --check preview mode
-- [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
+- [Autoscaling workflows](https://docs.kici.dev/user/workflows/autoscaling-workflows/): Write TypeScript provisioning and teardown workflows that boot and delete ephemeral cloud agents in response to the event scaler
 
 ## Providers
 

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

@@ -7,6 +7,21 @@ export declare const PLANE_STAMP_VERSION = 3;
 /**
  * Root directory of the local dev plane's state, following the same
  * `KICI_CONFIG_DIR` → `~/.kici` convention the rest of the CLI uses.
+ *
+ * RESOLVED THROUGH SYMLINKS, deliberately. The plane is a singleton on fixed
+ * ports, so a caller may reach it through a config dir that only symlinks
+ * `local` at the durable one — `pnpm deploy:stg` does exactly that, to run
+ * against a throwaway config dir carrying no credentials while still reusing
+ * the warm plane.
+ *
+ * Without resolving, the plane's Postgres is started with a data directory
+ * addressed through that ephemeral path and keeps it open. When the caller
+ * removes its temp dir, Postgres PANICs — `could not open file
+ * "<tmp>/local/pgdata/global/pg_control"` — and shuts the whole plane down,
+ * taking every later phase with it. Resolving first means Postgres only ever
+ * sees the durable path, so a caller's temp dir can come and go beneath it.
+ *
+ * A path that does not exist yet resolves to itself: a fresh plane creates it.
  */
 export declare function planeRoot(): string;
 /**

package/dist/local-plane/paths.js

@@ -1,5 +1,6 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import path from "node:path";
+import fs from "node:fs";
 import os from "node:os";
 //#region src/local-plane/paths.ts
 /**
@@ -11,10 +12,30 @@ const PLANE_STAMP_VERSION = 3;
 /**
 * Root directory of the local dev plane's state, following the same
 * `KICI_CONFIG_DIR` → `~/.kici` convention the rest of the CLI uses.
+*
+* RESOLVED THROUGH SYMLINKS, deliberately. The plane is a singleton on fixed
+* ports, so a caller may reach it through a config dir that only symlinks
+* `local` at the durable one — `pnpm deploy:stg` does exactly that, to run
+* against a throwaway config dir carrying no credentials while still reusing
+* the warm plane.
+*
+* Without resolving, the plane's Postgres is started with a data directory
+* addressed through that ephemeral path and keeps it open. When the caller
+* removes its temp dir, Postgres PANICs — `could not open file
+* "<tmp>/local/pgdata/global/pg_control"` — and shuts the whole plane down,
+* taking every later phase with it. Resolving first means Postgres only ever
+* sees the durable path, so a caller's temp dir can come and go beneath it.
+*
+* A path that does not exist yet resolves to itself: a fresh plane creates it.
 */
 function planeRoot() {
 	const base = process.env.KICI_CONFIG_DIR ?? path.join(os.homedir(), ".kici");
-	return path.join(base, "local");
+	const root = path.join(base, "local");
+	try {
+		return fs.realpathSync(root);
+	} catch {
+		return root;
+	}
 }
 /**
 * Absolute paths for every artefact the plane persists under its state root.

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

@@ -19,8 +19,8 @@ import { generateKeyPairSync, randomBytes } from "node:crypto";
 */
 function currentBuildIdentity() {
 	return {
-		version: "0.5.0",
-		buildCommit: "cb51c7d1e"
+		version: "0.6.1",
+		buildCommit: "d32193b6b"
 	};
 }
 /**

package/dist/local-plane/port-holder.js

@@ -15,7 +15,7 @@ import net from "node:net";
 const defaultExec = (cmd, args) => new Promise((resolve) => {
 	execFile(cmd, args, {
 		timeout: 5e3,
-		maxBuffer: 8 * 1024 * 1024
+		maxBuffer: 8388608
 	}, (err, stdout) => {
 		const raw = err?.code;
 		resolve({

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

@@ -3,7 +3,7 @@
  * `TS_CONST_PINS` in hack/containers-lock.ts (identity
  * docker.io/library/postgres+alpine), so a lock bump rewrites it in place.
  */
-export declare const PLANE_PG_IMAGE = "docker.io/library/postgres:18.4-alpine";
+export declare const PLANE_PG_IMAGE = "docker.io/library/postgres:18.6-alpine";
 /** Name of the fallback podman Postgres container. */
 export declare const PLANE_PG_CONTAINER = "kici-local-postgres";
 export type PlanePgHandle = {
@@ -11,13 +11,6 @@ export type PlanePgHandle = {
     kind: 'embedded' | 'podman';
     stop(): Promise<void>;
 };
-declare let readyPoller: typeof defaultReadyPoller;
-/** Test seam: override the podman readiness poller. */
-export declare function __setReadyPollerForTest(fn: typeof readyPoller): void;
-declare let embeddedDaemon: typeof defaultEmbeddedDaemon;
-/** Test seam: override the embedded postmaster daemonizer. */
-export declare function __setEmbeddedDaemonForTest(fn: typeof embeddedDaemon): void;
-declare function defaultReadyPoller(_port: number): Promise<boolean>;
 /**
  * Whether this plane's embedded postmaster is already serving `port`.
  *
@@ -31,13 +24,6 @@ declare function defaultReadyPoller(_port: number): Promise<boolean>;
  * one this plane can reuse.
  */
 export declare function embeddedClusterIsServing(port: number): Promise<boolean>;
-/**
- * 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.
- */
-declare function defaultEmbeddedDaemon(port: number): Promise<void>;
 /**
  * Stop the plane's Postgres by backend kind. Handle-independent so a separate
  * CLI invocation (`kici local down`) can tear down what `up` started.
@@ -51,6 +37,7 @@ export declare function stopPlanePostgres(kind: 'embedded' | 'podman'): Promise<
  */
 export declare function startPlanePostgres(opts?: {
     forcePodman?: boolean;
+    readyPoller?: (port: number) => Promise<boolean>;
+    embeddedDaemon?: (port: number) => Promise<void>;
 }): Promise<PlanePgHandle>;
-export {};
 //# sourceMappingURL=postgres.d.ts.map

package/dist/local-plane/postgres.js

@@ -13,19 +13,9 @@ import EmbeddedPostgres from "embedded-postgres";
 * `TS_CONST_PINS` in hack/containers-lock.ts (identity
 * docker.io/library/postgres+alpine), so a lock bump rewrites it in place.
 */
-const PLANE_PG_IMAGE = "docker.io/library/postgres:18.4-alpine";
+const PLANE_PG_IMAGE = "docker.io/library/postgres:18.6-alpine";
 /** Name of the fallback podman Postgres container. */
 const PLANE_PG_CONTAINER = "kici-local-postgres";
-let readyPoller = defaultReadyPoller;
-/** Test seam: override the podman readiness poller. */
-function __setReadyPollerForTest(fn) {
-	readyPoller = fn;
-}
-let embeddedDaemon = defaultEmbeddedDaemon;
-/** Test seam: override the embedded postmaster daemonizer. */
-function __setEmbeddedDaemonForTest(fn) {
-	embeddedDaemon = fn;
-}
 async function defaultReadyPoller(_port) {
 	for (let i = 0; i < 60; i++) try {
 		await $`podman exec ${PLANE_PG_CONTAINER} pg_isready -U kici`.quiet();
@@ -56,7 +46,8 @@ function resolvePgCtl() {
 		"win32:x64": "@embedded-postgres/windows-x64"
 	}[`${platform}:${arch}`];
 	if (!pkg) throw new Error(`unsupported platform for embedded Postgres: ${platform}/${arch}`);
-	const entry = createRequire(createRequire(import.meta.url).resolve("embedded-postgres")).resolve(pkg);
+	const require = createRequire(import.meta.url);
+	const entry = createRequire(require.resolve("embedded-postgres")).resolve(pkg);
 	const binName = platform === "win32" ? "pg_ctl.exe" : "pg_ctl";
 	return path.resolve(path.dirname(entry), "..", "native", "bin", binName);
 }
@@ -119,13 +110,15 @@ async function embeddedClusterIsServing(port) {
 async function defaultEmbeddedDaemon(port) {
 	const { pgData, logFile } = planePaths();
 	if (await embeddedClusterIsServing(port)) return;
-	await $`${resolvePgCtl()} -D ${pgData} -o ${`-p ${port}`} -l ${`${logFile}.pg`} -w start`.quiet();
+	const pgCtl = resolvePgCtl();
+	await $`${pgCtl} -D ${pgData} -o ${`-p ${port}`} -l ${`${logFile}.pg`} -w start`.quiet();
 }
 /** Stop the detached embedded postmaster (handle-independent, reads the data dir). */
 async function stopEmbeddedDaemon() {
 	const { pgData } = planePaths();
 	if (!fs.existsSync(path.join(pgData, "postmaster.pid"))) return;
-	await $`${resolvePgCtl()} -D ${pgData} stop -m fast`.quiet().catch(() => {});
+	const pgCtl = resolvePgCtl();
+	await $`${pgCtl} -D ${pgData} stop -m fast`.quiet().catch(() => {});
 }
 /**
 * Stop the plane's Postgres by backend kind. Handle-independent so a separate
@@ -142,6 +135,8 @@ async function stopPlanePostgres(kind) {
 * (or when forced via `forcePodman` / `KICI_LOCAL_PG_MODE=podman`).
 */
 async function startPlanePostgres(opts = {}) {
+	const readyPoller = opts.readyPoller ?? defaultReadyPoller;
+	const embeddedDaemon = opts.embeddedDaemon ?? defaultEmbeddedDaemon;
 	const { postgres: port } = planePorts();
 	const url = `postgres://kici:kici@127.0.0.1:${port}/kici_local`;
 	if (!(opts.forcePodman || process.env.KICI_LOCAL_PG_MODE === "podman")) try {
@@ -182,6 +177,6 @@ async function startPlanePostgres(opts = {}) {
 	};
 }
 //#endregion
-export { PLANE_PG_CONTAINER, PLANE_PG_IMAGE, __setEmbeddedDaemonForTest, __setReadyPollerForTest, embeddedClusterIsServing, startPlanePostgres, stopPlanePostgres };
+export { PLANE_PG_CONTAINER, PLANE_PG_IMAGE, embeddedClusterIsServing, startPlanePostgres, stopPlanePostgres };
 
 //# sourceMappingURL=postgres.js.map

package/dist/lockfile/generator.d.ts

@@ -36,6 +36,18 @@ export declare function detectGitRoot(): string;
  * For yarn the prefix also carries the flavor (`yarn-classic` / `yarn-berry`),
  * so a classic-layout dep-cache tarball is never restored into a berry install.
  *
+ * The detected manager only orders the search; it never restricts it. Detection
+ * falls back to the AMBIENT `npm_config_user_agent` when a directory carries no
+ * signal of its own, so a repo whose root holds neither a `package.json` nor a
+ * lockfile is reported as whatever manager happened to invoke the compiler. A
+ * repo compiled under pnpm that keeps an npm `.kici/package-lock.json` was
+ * therefore searched for `pnpm-lock.yaml` only, found none, and got no hash at
+ * all — which silently disables the orchestrator's dependency cache for it, so
+ * every agent installs from the registry and an agent with no registry route
+ * cannot run the job at all. Searching every manager's candidates after the
+ * detected one's keeps the detected manager authoritative where it has real
+ * evidence, and still finds the lockfile that is actually on disk.
+ *
  * @param gitRoot - Absolute path to git repository root
  * @returns Hex SHA-256 hash string, or null if no lockfile is found
  */

package/dist/lockfile/generator.js

@@ -66,16 +66,39 @@ function detectGitRoot() {
 * For yarn the prefix also carries the flavor (`yarn-classic` / `yarn-berry`),
 * so a classic-layout dep-cache tarball is never restored into a berry install.
 *
+* The detected manager only orders the search; it never restricts it. Detection
+* falls back to the AMBIENT `npm_config_user_agent` when a directory carries no
+* signal of its own, so a repo whose root holds neither a `package.json` nor a
+* lockfile is reported as whatever manager happened to invoke the compiler. A
+* repo compiled under pnpm that keeps an npm `.kici/package-lock.json` was
+* therefore searched for `pnpm-lock.yaml` only, found none, and got no hash at
+* all — which silently disables the orchestrator's dependency cache for it, so
+* every agent installs from the registry and an agent with no registry route
+* cannot run the job at all. Searching every manager's candidates after the
+* detected one's keeps the detected manager authoritative where it has real
+* evidence, and still finds the lockfile that is actually on disk.
+*
 * @param gitRoot - Absolute path to git repository root
 * @returns Hex SHA-256 hash string, or null if no lockfile is found
 */
 function computeLockfileHash(gitRoot) {
 	const pm = detectPackageManagerSync(gitRoot) === PackageManager.Npm ? detectPackageManagerSync(path.join(gitRoot, ".kici")) : detectPackageManagerSync(gitRoot);
-	const candidates = pm === PackageManager.Pnpm ? [path.join(gitRoot, "pnpm-lock.yaml"), path.join(gitRoot, ".kici", "pnpm-lock.yaml")] : pm === PackageManager.Yarn ? [path.join(gitRoot, "yarn.lock"), path.join(gitRoot, ".kici", "yarn.lock")] : [path.join(gitRoot, ".kici", "package-lock.json")];
-	const prefix = pm === PackageManager.Yarn ? `${pm}-${detectYarnFlavorSync(detectPackageManagerSync(gitRoot) === PackageManager.Yarn ? gitRoot : path.join(gitRoot, ".kici"))}` : pm;
-	for (const lockfilePath of candidates) try {
-		return sha256(`${prefix}\n${readFileSync(lockfilePath, "utf-8")}`);
-	} catch {}
+	const byManager = (m) => m === PackageManager.Pnpm ? [path.join(gitRoot, "pnpm-lock.yaml"), path.join(gitRoot, ".kici", "pnpm-lock.yaml")] : m === PackageManager.Yarn ? [path.join(gitRoot, "yarn.lock"), path.join(gitRoot, ".kici", "yarn.lock")] : [path.join(gitRoot, ".kici", "package-lock.json")];
+	const order = [pm, ...[
+		PackageManager.Npm,
+		PackageManager.Pnpm,
+		PackageManager.Yarn
+	].filter((m) => m !== pm)];
+	for (const manager of order) for (const lockfilePath of byManager(manager)) {
+		let content;
+		try {
+			content = readFileSync(lockfilePath, "utf-8");
+		} catch {
+			continue;
+		}
+		const prefix = manager === PackageManager.Yarn ? `${manager}-${detectYarnFlavorSync(path.dirname(lockfilePath))}` : manager;
+		return sha256(`${prefix}\n${content}`);
+	}
 	return null;
 }
 /**
@@ -112,16 +135,17 @@ function generateLockFile(workflowsWithSource) {
 	const workflows = workflowsWithSource.map(({ workflow, source, bundleSource }) => {
 		return transformWorkflow(workflow, path.relative(gitRoot, source.file).replaceAll("\\", "/"), formatExportRef(source), bundleSource, gitRoot);
 	});
+	const contentHash = sha256(JSON.stringify({
+		schemaVersion: SCHEMA_VERSION$1,
+		minReaderVersion: BREAKING_FLOOR$1,
+		source: topLevelSource,
+		workflows
+	}));
 	return {
 		schemaVersion: SCHEMA_VERSION$1,
 		minReaderVersion: BREAKING_FLOOR$1,
 		source: topLevelSource,
-		contentHash: sha256(JSON.stringify({
-			schemaVersion: SCHEMA_VERSION$1,
-			minReaderVersion: BREAKING_FLOOR$1,
-			source: topLevelSource,
-			workflows
-		})),
+		contentHash,
 		...lockfileHash && { lockfileHash },
 		workflows
 	};
@@ -209,12 +233,14 @@ function serializeRegexEntry(entry, ctx) {
 	try {
 		re = new RegExp(pattern, flags);
 	} catch (err) {
-		throw compilerError("E123", `${ctx}: invalid regex — ${err instanceof Error ? err.message : String(err)}`);
+		const reason = err instanceof Error ? err.message : String(err);
+		throw compilerError("E123", `${ctx}: invalid regex — ${reason}`);
 	}
 	try {
 		assertSafeRegex(re.source, re.flags, ctx);
 	} catch (err) {
-		throw compilerError("E123", `${ctx}: ${err instanceof Error ? err.message : String(err)}`);
+		const reason = err instanceof Error ? err.message : String(err);
+		throw compilerError("E123", `${ctx}: ${reason}`);
 	}
 	return `/${re.source}/${re.flags}`;
 }
@@ -660,7 +686,7 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 		location: jobLocation,
 		suggestion: "Set exactly one of runsOn (single agent) or runsOnAll (fan-out to every matching agent)."
 	});
-	if (job.runsOn === void 0 && job.runsOnAll === void 0) throw compilerError("E109", `job '${job.name}': one of runsOn or runsOnAll is required`, {
+	if (job.invoke === void 0 && job.runsOn === void 0 && job.runsOnAll === void 0) throw compilerError("E109", `job '${job.name}': one of runsOn or runsOnAll is required`, {
 		location: jobLocation,
 		suggestion: "Add runsOn: \"kici:os:linux\" (or another agent label) to the job."
 	});
@@ -700,8 +726,15 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 		...job.runsOnAll !== void 0 && { runsOnAll: normalizeRunsOnAllToMatchers(job.runsOnAll, `job '${job.name}' runsOnAll`) },
 		...job.onUnreachable !== void 0 && { onUnreachable: job.onUnreachable },
 		...job.includeUninitialized !== void 0 && { includeUninitialized: job.includeUninitialized },
+		...job.gitCredentials !== void 0 && { gitCredentials: job.gitCredentials },
 		...job.maxParallel !== void 0 && { maxParallel: job.maxParallel },
 		...job.failFast !== void 0 && { failFast: job.failFast },
+		...job.invoke !== void 0 && { invoke: {
+			event: job.invoke.event,
+			scope: job.invoke.scope,
+			...job.invoke.payload !== void 0 && { payload: job.invoke.payload },
+			...job.invoke.optional === true && { optional: true }
+		} },
 		...resolveNeedsForLock(job.needs, uuidToName),
 		steps: transformSteps(job.steps, gitRoot, jobLocation),
 		matrix: job.matrix ? transformMatrix(job.matrix, job.name, configPath) : void 0,

package/dist/postinstall.js

@@ -26,7 +26,8 @@ async function detectDevelopmentMode() {
 	if (process.env.KICI_DEV === "true") return true;
 	try {
 		const rootDir = process.env.INIT_CWD || process.cwd();
-		const content = await readFile(path.join(rootDir, "package.json"), "utf-8");
+		const rootPkgPath = path.join(rootDir, "package.json");
+		const content = await readFile(rootPkgPath, "utf-8");
 		return JSON.parse(content).kici?.development === true;
 	} catch {
 		return false;

package/dist/remote/config.d.ts

@@ -35,22 +35,9 @@ export interface GlobalConfig {
  *
  * Resolution order:
  *   1. `KICI_CONFIG_DIR`, when set to a non-empty value.
- *   2. A hard refusal when `KICI_TEST_ISOLATION` is present. A developer
- *      machine's `~/.kici/config` names a real endpoint and carries a live
- *      PAT, so a test process that reads it authenticates against whatever
- *      that config points at — in practice, production. Every test that needs
- *      a config must name its own isolated directory.
- *   3. `~/.kici`.
+ *   2. `~/.kici`.
  *
- * `KICI_TEST_ISOLATION` is set by this repository's own vitest configs, via
- * `hack/lib/vitest-isolation.ts`. It is deliberately a KiCI-owned name rather
- * than the runner's `VITEST`: `kici` is a compat-protected CLI, and `VITEST`
- * is a third-party marker that propagates into spawned children, so keying off
- * it would break a customer whose vitest test shells out to `kici`.
- *
- * `env` is injectable so this module's own tests can exercise every branch.
- * It is NOT an opt-out: production call sites pass no argument and inherit the
- * guard.
+ * `env` is injectable so this module's own tests can exercise both branches.
  */
 export declare function getConfigDir(env?: NodeJS.ProcessEnv): string;
 /**

package/dist/remote/config.js

@@ -33,26 +33,12 @@ function sanitizeConfig(raw) {
 *
 * Resolution order:
 *   1. `KICI_CONFIG_DIR`, when set to a non-empty value.
-*   2. A hard refusal when `KICI_TEST_ISOLATION` is present. A developer
-*      machine's `~/.kici/config` names a real endpoint and carries a live
-*      PAT, so a test process that reads it authenticates against whatever
-*      that config points at — in practice, production. Every test that needs
-*      a config must name its own isolated directory.
-*   3. `~/.kici`.
+*   2. `~/.kici`.
 *
-* `KICI_TEST_ISOLATION` is set by this repository's own vitest configs, via
-* `hack/lib/vitest-isolation.ts`. It is deliberately a KiCI-owned name rather
-* than the runner's `VITEST`: `kici` is a compat-protected CLI, and `VITEST`
-* is a third-party marker that propagates into spawned children, so keying off
-* it would break a customer whose vitest test shells out to `kici`.
-*
-* `env` is injectable so this module's own tests can exercise every branch.
-* It is NOT an opt-out: production call sites pass no argument and inherit the
-* guard.
+* `env` is injectable so this module's own tests can exercise both branches.
 */
 function getConfigDir(env = process.env) {
 	if (env.KICI_CONFIG_DIR) return env.KICI_CONFIG_DIR;
-	if (env.KICI_TEST_ISOLATION) throw new Error("Refusing to read the ambient ~/.kici config from a test process. Set KICI_CONFIG_DIR to an isolated directory for this run — the developer machine config may point at production.");
 	return path.join(os.homedir(), ".kici");
 }
 /**