@kici-dev/compiler 0.4.0 → 0.6.0

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

@@ -313,12 +313,16 @@ The `ProviderRegistry` maps routing keys to provider bundles. Each routing key (
 - `WebhookNormalizer` (required) -- normalizes incoming webhooks to a standard format
 - `LockFileFetcher` -- fetches lock files from the repository
 - `ChangedFilesFetcher` -- determines which files changed
+- `FileContentsFetcher` -- reads arbitrary repository files at a ref, for the declarative content-requirements (`requires`) filter
 - `CloneTokenProvider` -- generates clone tokens for agents
 - `RepoUrlBuilder` -- builds clone URLs and raw file URLs
-- `ContributorResolver` -- resolves contributor permissions for trust-tier gating
 - `CheckStatusPoster` -- posts check statuses (approval/hold) to the git provider
 
-A GitHub App source populates all seven. A plain generic webhook source carries only the normalizer -- it has no repository API to fetch a lock file, resolve a contributor, or post a check against -- so the pipeline skips the stages whose interface is absent rather than failing the delivery.
+A bundle also carries a `hasForkModel` flag, set for a provider whose head ref can live outside the base repository. It is what admits a pull-request event to the org fork switch. GitHub sets it; a generic source (whose trust boundary is its verification secret) and a local source (whose trust boundary is on-disk ownership) do not.
+
+A GitHub App source populates all seven. The file-contents capability arrives as a per-delivery factory rather than a prebuilt instance: a GitHub client is scoped to one installation, and the installation id is known only once the delivery's credentials are resolved.
+
+A plain generic webhook source carries only the normalizer, because it has no repository API to fetch a lock file or post a check against. The pipeline skips the stages whose interface is absent rather than failing the delivery.
 
 Provider registrations are managed via the `sources` database table, not via `SharedConfig`. When the orchestrator connects to the Platform relay, it reads source records from the DB and sends `source.register` messages. Changes to sources (add/remove) are detected via PostgreSQL LISTEN/NOTIFY on the `sources_change` channel and pushed to the Platform via `source.secrets` and `source.register`/`source.deregister`.
 
@@ -406,10 +410,11 @@ GitHub  -->  Platform Relay  -->  Orchestrator  -->  Agent
 12. **Orchestrator extracts registrations** on default-branch pushes: persists registerable workflows (event, schedule, lifecycle triggers) for cluster-wide event matching.
 13. **Orchestrator notifies the event router** on default-branch pushes: after the registrations are persisted, emits a `registration.updated` event via `eventRouter.emit()` (if event routing is active). Workflow event subscriptions are the persisted registrations themselves, matched at emit time through the registration index.
 14. **Orchestrator fetches changed files** via the provider's `ChangedFilesFetcher` for path-based trigger filtering (skipped when no workflow uses path filters).
-15. **Orchestrator matches triggers** against lock file using `matchAllWorkflows()` from `@kici-dev/engine`.
-16. **Orchestrator checks caches** for source tarballs and dependency tarballs.
-17. **Orchestrator dispatches jobs** to agents via the job queue and WebSocket.
-18. **Orchestrator persists a delivery row** keyed by `(org_id, delivery_id)` to its own `event_log`, including a pointer to the gzipped payload in object storage. The orchestrator's delivery log is surfaced in the dashboard's Settings → Event log tab. See [`webhook-delivery.md`](https://docs.kici.dev/architecture/webhooks/webhook-delivery/#delivery-log).
+15. **Orchestrator matches triggers** against the lock file using `matchWorkflowsForEvent()` from `@kici-dev/engine` -- an event-type-bucketed candidate scan that evaluates only the workflows subscribed to this event type. (The single-registration global / cross-source paths evaluate one lock entry at a time via `matchAllWorkflows()`.)
+16. **Orchestrator applies the content-requirements filter** to the matched candidates: for each trigger that declares `requires`, it reads the named source files at the event's ref through the provider's `FileContentsFetcher` (once per distinct `(repo, sha, path)` via an LRU cache) and evaluates the declarative requirement. Candidates that fail -- or that cannot be evaluated at all (unreadable or oversize content, a fetch error, no fetcher wired) -- are dropped before dispatch with the concrete reason logged. No workflow code runs at this stage. Skipped entirely when no matched trigger declares `requires`.
+17. **Orchestrator checks caches** for source tarballs and dependency tarballs.
+18. **Orchestrator dispatches jobs** to agents via the job queue and WebSocket.
+19. **Orchestrator persists a delivery row** keyed by `(org_id, delivery_id)` to its own `event_log`, including a pointer to the gzipped payload in object storage. The orchestrator's delivery log is surfaced in the dashboard's Settings → Event log tab. See [`webhook-delivery.md`](https://docs.kici.dev/architecture/webhooks/webhook-delivery/#delivery-log).
 
 ## Job execution flow
 
@@ -437,7 +442,18 @@ Orchestrator                         Agent                    Sandbox (child pro
 
 ### Agent pipeline
 
-The agent delegates job execution to an `ExecutionSandbox` (container, bare-metal, or firecracker). The sandbox runs customer code in an isolated child process -- never in the agent's V8 isolate. Four job types are handled: execution jobs (sandbox), build-only jobs (in-process, cache population), init-only jobs (in-process, dynamic field resolution), and DynamicJobFn evaluation jobs (in-process, runtime job generation). See [Job execution lifecycle](https://docs.kici.dev/architecture/execution/job-execution/) for details.
+The agent delegates job execution to an `ExecutionSandbox` (container, bare-metal, or firecracker). The sandbox runs customer code in an isolated child process -- never in the agent's V8 isolate.
+
+Six job types are handled. Only the first uses a sandbox; the other five run in-process, because they never execute customer workflow steps:
+
+- **Execution jobs** -- the standard sandbox path.
+- **Init-only jobs** -- dynamic field resolution.
+- **Global-eval-round jobs** -- filters and generators for the candidate global workflows of one workflow repo.
+- **DynamicJobFn evaluation jobs** -- runtime job generation.
+- **Bring-up jobs** -- init-runner SSH bring-up. No clone, no sandbox.
+- **Build-only jobs** -- cache population.
+
+See [Job execution lifecycle](https://docs.kici.dev/architecture/execution/job-execution/) for details.
 
 1. **Report running** -- Send `job.status: running` immediately upon accepting the dispatch
 2. **Sandbox selection** -- Determine execution mode (container, bare-metal, firecracker) from job config and environment
@@ -510,7 +526,7 @@ Build Job Dispatch --> Build Agent (kici:role:builder + matching kici:os:/kici:a
   |                      |-- Pack .kici/ source (portable tar.gz, excludes node_modules)
   |                      |-- Pack .kici/node_modules (portable tar.gz)
   |                      |-- Upload source tarball to cache (source/{contentHash}.tar.gz)
-  |                      |-- Upload deps tarball to cache (deps/{plat}-{arch}/{lockfileHash}.tar.gz)
+  |                      |-- Upload deps tarball to cache (deps/{plat}-{arch}/{depsHash}.tar.gz)
   |                      |-- Upload deps companion .hash file
   |                      |-- Report success (cache.upload.complete × 2)
   |                      |
@@ -525,7 +541,7 @@ Execution Job Dispatch --> Execution Agent
   |                          |
   |                          |-- Download source tarball (sourceTarUrl) -> extract to workDir/.kici/
   |                          |-- Download deps tarball (depsUrl) -> verify SHA-256 -> extract to .kici/node_modules/
-  |                          |-- Register @kici-dev/shared/ts-loader-hook
+  |                          |-- Register @kici-dev/core/ts-loader-hook
   |                          |-- Verify workflow contentHash against lock file (drift guard)
   |                          |-- Dynamic-import workflow .ts
   |                          |-- Execute steps
@@ -584,7 +600,7 @@ Dep cache misses alone do **not** trigger a build job. Deps are platform-specifi
 
 ### Cross-source / no-contentHash workflows
 
-- **Lock files without `contentHash`** (schema v1) skip the source cache entirely; agents compile from source. Regenerate lock files with `kici compile` to enable caching. The current lock file schema version is 32.
+- **Lock files without `contentHash`** (schema v1) skip the source cache entirely; agents compile from source. Regenerate lock files with `kici compile` to enable caching. The current lock file schema version is 39.
 - **Cross-source / global-workflow dispatch** (a workflow registered against source A fired by a webhook on source B) bypasses both caches. The registration's lock file entry still carries `contentHash`, but the cross-source path always clone-and-installs — the eval temp dir doesn't ship `@kici-dev/sdk`. The execution agent still verifies `contentHash` against the cloned source for drift detection.
 
 ### Build deduplication
@@ -624,7 +640,10 @@ Both source and dep caches use `S3CacheStorage` as the sole backend. The `CacheS
 Cache keys reflect that source tarballs and deps have different platform characteristics:
 
 - **Source:** `source/{contentHash}.tar.gz` — platform-agnostic. Raw TypeScript source is identical regardless of CPU architecture, so one entry is shared across all platforms. `contentHash` is the per-workflow hash from the lock file (`SHA-256(COMPILE_SCHEMA_VERSION + ":" + rawSource [+ "\0" + assetDigest])`, where `COMPILE_SCHEMA_VERSION = 5` and line endings are normalized to LF so the hash agrees across platforms).
-- **Deps:** `deps/{platform}-{arch}/{lockfileHash}.tar.gz` (e.g., `deps/linux-arm64/def456.tar.gz`) — platform-specific. Native dependencies in `node_modules` differ across architectures, so each platform/arch combination gets its own cache entry.
+- **Deps:** `deps/{platform}-{arch}/{depsHash}.tar.gz`, with a
+  `deps/{platform}-{arch}/{lockfileHash}.hash` pointer holding that hash — the
+  tarball is addressed by its own content, so two builds sharing a lock file
+  cannot leave a tarball and an integrity hash that disagree. Platform-specific. Native dependencies in `node_modules` differ across architectures, so each platform/arch combination gets its own cache entry.
 
 The orchestrator derives the target platform/arch for dep cache lookups by probing `AgentRegistry.findAvailable()` with the workflow's first job's `runsOn` labels to find a representative matching agent, then using that agent's platform and arch. Falls back to `linux/x64` if no matching agents are registered.
 
@@ -829,7 +848,7 @@ Agent                          Orchestrator
 
 ### Registration extraction flow
 
-When code is pushed to the default branch, the orchestrator extracts event-triggered workflows from the lock file and stores them as registrations for cluster-wide event matching.
+When code is pushed to the default branch, the orchestrator extracts registerable workflows from the lock file and stores them as registrations for cluster-wide event matching. Non-Git triggers (`kici_event`, `schedule`, `generic_webhook`, …) live there because they have no per-repo lock-file pipeline to fall back on; Git-provider triggers (`push`, `pr`, `tag`, …) are indexed too, so the cross-source dispatch path can resolve them by `(customer_id, repo_identifier)` when a generic webhook targets an externally-hosted repo. For same-source Git events the per-event lock-file pipeline remains the primary matcher — registration is an additive index.
 
 ```
 Git Push to Default Branch
@@ -842,8 +861,15 @@ GitHub Webhook -> Platform Relay -> Orchestrator Processor
     |-- extractRegisterableWorkflows(fullLockFile)
     |       |-- For each workflow entry in lock file:
     |       |     Check if any trigger type is registerable
-    |       |     (kici_event, workflow_complete, job_complete,
-    |       |      generic_webhook, schedule, lifecycle)
+    |       |     (the RegisterableTriggerType enum — the non-Git
+    |       |      set kici_event, workflow_complete,
+    |       |      workflows_failed_batch, job_complete,
+    |       |      generic_webhook, schedule, lifecycle, webhook,
+    |       |      plus every Git-provider trigger: push, pr, tag,
+    |       |      comment, review, review_comment, release,
+    |       |      dispatch, create, delete, status, workflow_run,
+    |       |      fork, star, watch)
+    |       |     ... or the workflow has repo patterns (global workflow)
     |       |-- Return array of registerable workflows
     |
     |-- globalWorkflowPolicy.isWorkflowRepoAllowed() (if policy configured)
@@ -1221,7 +1247,7 @@ The Platform tier exposes a `/ws/browser` WebSocket endpoint for dashboard clien
 - [Architecture overview](https://docs.kici.dev/architecture/overview/) -- three-tier model and component responsibilities
 - [Protocol messages](https://docs.kici.dev/architecture/protocol-messages/) -- WebSocket message schemas
 - [Event system internals](https://docs.kici.dev/architecture/webhooks/event-system/) -- event router, registration model, cron scheduler
-- [Execution lifecycle](https://docs.kici.dev/architecture/execution/state-machine/) -- run, job, and step status vocabularies and terminal states
+- [Execution status vocabulary](https://docs.kici.dev/architecture/execution/state-machine/) -- run, job, and step status vocabularies and terminal states
 - [Webhook delivery](https://docs.kici.dev/architecture/webhooks/webhook-delivery/) -- detailed webhook processing pipeline
 - [Operator: dependency caching](https://docs.kici.dev/operator/dependency-caching/) -- configuration guide
 - [Operator: monitoring & tracing](https://docs.kici.dev/operator/observability/monitoring/) -- trace fields and Loki queries
@@ -1295,7 +1321,7 @@ The orchestrator is the execution brain. It decides what to run and dispatches w
 - **Job queue** -- PostgreSQL-backed FIFO queue for reliable dispatch.
 - **Webhook pipeline** -- Dedup, event mapping, lock file fetch, trigger matching, and job dispatch in a single pipeline.
 - **Multi-orchestrator clustering** -- Optional peer-to-peer coordination via direct WebSocket connections. Enables cross-architecture job routing (e.g., x64 coordinator reroutes arm64 jobs to a peer), high availability, and dedicated coordinator topologies. Uses Raft consensus for leader election (orphan recovery). See [Multi-Orchestrator Architecture](https://docs.kici.dev/architecture/clustering/multi-orchestrator/).
-- **Auto-scaler** -- Optional pluggable module for ephemeral agent provisioning. Supports containers (Docker/Podman), bare-metal processes, and Firecracker microVMs as backends. Spawns agents on demand when no matching agent is connected, with label-based routing, two-level capacity limits (global + per-backend), warm pools, YAML configuration (`scalers.d/` directory support), and SIGHUP reload. Disabled by default -- orchestrator works without it.
+- **Auto-scaler** -- Optional pluggable module for ephemeral agent provisioning. Four backends are configurable: containers (Docker/Podman), bare-metal processes, Firecracker microVMs, and the event backend, which performs no local compute -- it emits reserved scale-up / scale-down events that a customer-authored provisioning workflow consumes to boot and tear down a cloud instance. Spawns agents on demand when no matching agent is connected, with label-based routing, two-level capacity limits (global + per-backend), warm pools, YAML configuration (`scalers.d/` directory support), and SIGHUP reload. Disabled by default -- orchestrator works without it.
 - **Independent database** -- Has its own PostgreSQL database separate from the Platform. Stores execution runs/jobs/steps, dispatch queue, webhook secrets, dedup cache, and scaler state. The orchestrator's `execution_runs` and `execution_jobs` are the authoritative source of truth. The Platform receives execution status updates via WebSocket messages (`execution.status`, `job.status.forward`).
 
 > Source: `packages/orchestrator/src/pipeline/processor.ts` (webhook pipeline), `packages/orchestrator/src/cluster/` (P2P coordination), `packages/orchestrator/src/scaler/` (auto-scaler module), `packages/orchestrator/src/server.ts` (Platform/hybrid entry point)
@@ -1305,6 +1331,7 @@ The orchestrator is the execution brain. It decides what to run and dispatches w
 The agent is the execution worker. It runs on customer infrastructure and has full access to customer code.
 
 - **Repository cloning** -- Clones the target repo with token-based auth (token in HTTP headers, not URLs, to prevent leakage).
+- **Git credential helper** -- Registers a credential helper for the job's git operations. Every network operation asks the orchestrator's broker for a credential, so a token is minted seconds before use rather than held for the life of the job. Write access is opt-in and time-boxed: `ctx.repo.withWrite(...)` adds a repository-scoped grant for the duration of its callback and revokes it afterwards, with a TTL backstop.
 - **Step execution** -- Runs steps in declaration order with full `StepContext` (zx shell, logger, environment, workflow/job metadata). Steps wrapped in a `parallel()` group run concurrently behind a `maxParallel` window, and each child reports as its own observable step with its own logs, status, timing, and retry.
 - **Execution sandboxes** -- Runs the workflow runner as a separate child process with a sanitized environment, in one of three sandboxes: bare metal (process fork, with optional bubblewrap namespace isolation), a container runtime (the whole job lifecycle runs inside a disposable container), or inside a Firecracker microVM. Agent-internal credentials never reach customer workflow code.
 - **Log streaming** -- Chunked log streaming back to the orchestrator with configurable size limits.
@@ -1320,11 +1347,14 @@ The agent is the execution worker. It runs on customer infrastructure and has fu
 Shared business logic used by all three tiers. Single source of truth for cross-tier concerns. Has no internal `@kici-dev/*` dependencies -- only a handful of third-party libraries.
 
 - Protocol message schemas (Zod-based, direction-specific unions including dashboard REST-over-WS, browser live streaming, the test-relay control plane, log pull, run events, peer-to-peer, cluster join, and source registration)
-- Provider interfaces (WebhookNormalizer, LockFileFetcher, ChangedFilesFetcher, CloneTokenProvider, RepoUrlBuilder, ContributorResolver, CheckStatusPoster)
+- Provider interfaces (WebhookNormalizer, LockFileFetcher, ChangedFilesFetcher, FileContentsFetcher, CloneTokenProvider, RepoUrlBuilder, CheckStatusPoster), plus the deprecated `ContributorResolver` the pipeline no longer calls
+- Git credential vocabulary (forge names plus the credential reference, grant, request, and result shapes the SDK declares and the orchestrator's broker resolves) and the agent→orchestrator relay protocol its credential helper calls. See [Git credentials](https://docs.kici.dev/user/patterns/git-credentials/)
 - Trigger matching engine (branch, path, event evaluation)
+- Content-requirement matcher (the declarative `requires` filter -- pure data describing a query over the bytes of one source file at the event's ref, interpreted by the orchestrator via the `FileContentsFetcher` so no author code runs there) and the shared text-match vocabulary (`contains` / `notContains` / `matches` / `notMatches`) it shares with the commit-message trigger filter
 - Dispatch inputs (input descriptors, extraction from the trigger event, and coercion to typed values)
 - Matrix expansion and fanout (combination expansion with include/exclude, job-name suffix formatting, and materialization of one matrix or multi-host job into N dispatchable children)
-- Execution status vocabulary (run/job/step status enums + terminal-state sets; lifecycle owned by the orchestrator's execution tracker)
+- Execution status vocabulary (run/job/step status enums + terminal-state sets; lifecycle owned by the orchestrator's execution tracker) and its presentation layer (the total precedence order that decides which status wins a roll-up, legacy-spelling resolution, and the per-status failure classification every consumer asks about)
+- Job-kind discriminator, alongside the status enums. It separates a `standard` job running steps from an invoke `gate` and from the `proxy` job that mirrors a summoned run
 - Check mode (the idempotent run modes `apply` / `check` / `check-fail-on-drift` and the per-step outcome vocabulary)
 - Webhook signature verification (HMAC-SHA256, timing-safe)
 - WebSocket close codes (unified across all tiers)
@@ -1335,12 +1365,18 @@ Shared business logic used by all three tiers. Single source of truth for cross-
 - Approval requirements (normalized approver clauses shared by the orchestrator gate, the resolver, the held-run store, and the agent step round-trip)
 - Build provenance (in-toto statement schema, DSSE envelope, attestation bundle, verification)
 - Artifact name contract (the shared filesystem/URL-safe name schema the orchestrator, agent, and SDK all validate against)
-- Developer MCP tool schemas (argument schemas for the AI-agent tool surface)
+- Developer MCP tool schemas (argument schemas for the AI-agent tool surface) and the untrusted-content fence that wraps every repository- or contributor-supplied value an agent reads in a per-response random nonce, so log lines and error text cannot be read as instructions
+- Developer-operations contract (one row per workflow-developer operation declaring which entrypoints expose it -- the shared REST API behind the web UI and the `kici` CLI, the AI-agent tool surface, and a curated UI flag -- asserted against each real surface by congruence tests)
 - Label utilities (platform label derivation, runsOn normalization, `kici:*` set-only reserved namespace, role labels)
 - Host inventory (the canonical queryable host-roster schema shared by the orchestrator's roster store, the agent-facing inventory API, and the SDK's `ctx.kici.inventory`)
 - Audit policy and retention (per-action access-log sampling, warm-retention windows for cold-store eligibility, federated activity row schema)
-- Scaler backend type enum (`container`, `bare-metal`, `firecracker`, `kubernetes`)
+- Scaler backend type enum (`container`, `bare-metal`, `firecracker`, `kubernetes`, `event`) and the reserved `kici.` event-name prefix that keeps a user step from forging a system event
+- Job resource vocabulary (the requests/limits shape the SDK accepts, the compiler validates and emits, the orchestrator uses for capacity math and kernel-side enforcement, and the dashboard displays)
 - Registration trigger type enum (registerable trigger discriminator)
+- Sandbox capability set (the Linux capability names a container sandbox may add or drop, shared by the SDK validator, the compiler, and the dispatch resolver)
+- Plan tier vocabulary (the hosted plan tiers and the purchasable subset, shared by the Platform and the browser dashboard)
+- Infrastructure alert vocabulary (the diagnostics alert types and severities the Platform mints and the dashboard and `kici` CLI render)
+- Metric catalog (the generated Prometheus metric inventory, its naming policy, and metric-kind compatibility checks)
 - Bundler config (shared bundler configuration consumed by `e2e/helpers/service-deploy.ts`; the agent runtime uses the `@kici-dev/core/ts-loader-hook` to transform TypeScript on import, with no runtime bundler step)
 
 > Source: `packages/engine/src/`
@@ -1361,7 +1397,7 @@ It also runs the **local dev plane** -- an on-demand, fully local execution stac
 
 ### `@kici-dev/core`
 
-Light shared utilities with no server-side dependencies — JSON-structured logging, error helpers, human-readable formatting (`formatBytes`/`formatDuration`/`formatUptime`), cryptographic helpers (`sha256`/`sha256File`/`deriveSharedSecret`), zx initialization (`initZx()`), and the TypeScript loader hook that transforms TypeScript on import. It is the dependency-light core that the SDK, compiler, and `kici` CLI consume directly so they stay free of heavier server-only dependencies. `@kici-dev/shared` re-exports it, so existing `@kici-dev/shared` import paths keep working.
+Light shared utilities with no server-side dependencies. It provides JSON-structured logging, error helpers, async-local-storage request context, and human-readable formatting (`formatBytes`/`formatDuration`/`formatUptime`). It also provides cryptographic helpers (`sha256`/`sha256File`/`deriveSharedSecret` plus symmetric encrypt/decrypt), retry-backoff computation, and the shared diagnostics-result contract. The rest of its surface ships as subpath entry points: the temp-directory allocator and its garbage collector, package-manager detection, CI-environment detection, and the idempotent-step runner (the check / confirm / apply primitive behind idempotent steps). Finally it supplies zx initialization (`initZx()`) and the TypeScript loader hook that transforms TypeScript on import. It is the dependency-light core that the SDK, compiler, and `kici` CLI consume directly so they stay free of heavier server-only dependencies. `@kici-dev/shared` re-exports it, so existing `@kici-dev/shared` import paths keep working.
 
 > Source: `packages/core/src/`
 
@@ -1449,7 +1485,7 @@ The orchestrator connects outbound to the Platform WebSocket endpoint. After aut
 
 When multiple orchestrators are deployed, they establish direct WebSocket connections to each other on the `/ws/peer` endpoint. Peers are discovered via the Platform matchmaker (Platform/hybrid modes) or static configuration (`KICI_CLUSTER_PEERS` env var, independent mode). Connections are authenticated with a mutual pre-shared key (PSK). Traffic includes agent inventory heartbeats, job rerouting, progress reporting, cancel propagation, and Raft leader election. These messages never transit the Platform tier.
 
-> See [Multi-Orchestrator Architecture](https://docs.kici.dev/architecture/clustering/multi-orchestrator/) for clustering details and [Protocol Messages](https://docs.kici.dev/architecture/protocol/dashboard/#orchestrator-orchestrator-messages-peer-to-peer) for message schemas.
+> See [Multi-Orchestrator Architecture](https://docs.kici.dev/architecture/clustering/multi-orchestrator/) for clustering details and [Protocol Messages](https://docs.kici.dev/architecture/protocol/dashboard/#orchestrator---orchestrator-messages-peer-to-peer) for message schemas.
 
 ### Orchestrator ↔ Agent
 
@@ -1464,7 +1500,7 @@ KiCI uses application-level tenant isolation. The Platform dashboard API accepts
 ## See also
 
 - [Multi-Orchestrator Architecture](https://docs.kici.dev/architecture/clustering/multi-orchestrator/) -- P2P clustering, Raft consensus, job rerouting
-- [Execution lifecycle](https://docs.kici.dev/architecture/execution/state-machine/) -- run, job, and step status vocabularies and the tracker that owns lifecycle state
+- [Execution status vocabulary](https://docs.kici.dev/architecture/execution/state-machine/) -- run, job, and step status vocabularies and the tracker that owns lifecycle state
 - [Protocol Messages](https://docs.kici.dev/architecture/protocol-messages/) -- WebSocket message schemas for all three layers
 - [Webhook Delivery](https://docs.kici.dev/architecture/webhooks/webhook-delivery/) -- end-to-end trace of a webhook through all three tiers
 

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

@@ -340,8 +340,11 @@ kici logout
 This:
 
 1. Revokes the PAT on the server (preventing further use)
-2. Clears auth fields from the local config file
-3. Preserves non-auth settings (active org, default clusters, Platform endpoint)
+2. Detaches the local dev plane if it is attached, so a logged-out user is not left with a hybrid plane holding an orphaned orchestrator key
+3. Clears the auth fields from the local config file — the PAT, its id and expiry, your email, and the active organization
+4. Preserves the connection settings (per-org default clusters, Platform endpoint, orchestrator endpoint, OIDC issuer, routing key)
+
+Server revocation is best-effort: if the network call fails, the local config is still cleared.
 
 ## Organization management
 
@@ -502,11 +505,13 @@ Every `/api/v1/*` mutation that touches tenant-plane data is recorded in the ups
 
 The CLI stores authentication data in `~/.kici/config` with `0600` permissions (owner read/write only). The config file contains:
 
-- PAT token
-- PAT expiry date
+- PAT token, its server-side id, and its expiry date
+- The email address from your OIDC token
 - Active organization ID
 - Per-org default orchestrator clusters
-- Platform endpoint URL
+- Platform endpoint URL, orchestrator endpoint URL, and the OIDC issuer the PAT was minted against
+- Routing key for webhook source identification
+- API key, when you logged in with `--token`
 
 ## Troubleshooting
 
@@ -540,11 +545,11 @@ Two ways forward:
 
 A port below 1024 fails the same way, with a permissions message rather than an "in use" one: those ports need elevated privileges. Pick a port above 1024. A value that is not a port number at all — non-numeric, negative, or above 65535 — is rejected before the login starts, naming the value you set.
 
-### Device flow timeout
+### Device code expired
 
 This is the device flow's own expiry, not the browser flow's callback timeout above.
 
-The device flow has a 5-minute timeout. If it expires:
+The device code is issued by the identity provider, which also sets how long it lives. The CLI prints the lifetime with the code (`Code expires in N minutes`) and polls until you approve or the code expires. On expiry it stops with `Device code expired`. If that happens:
 
 - Run `kici login --device` again to get a new code
 - Ensure you're using the correct URL displayed by the CLI
@@ -605,7 +610,7 @@ The full command reference is split by area:
 - [Authoring & local dev](https://docs.kici.dev/user/cli/authoring-and-local/) — `compile`, `preview`, `local`, `fixture`, `types`, `workflows`, `hook`, `docs`
 - [Runs & approvals](https://docs.kici.dev/user/cli/runs-and-approvals/) — `run`, `runs`, `reject`, `approve`
 - [Account & org](https://docs.kici.dev/user/cli/account-and-org/) — `login`, `logout`, `init`, `org`, `pat`, `secrets`, `admin`, `orchestrators`, `endpoints`
-- [Notifications & diagnostics](https://docs.kici.dev/user/cli/notifications-and-diagnostics/) — `notifications`, `verify-attestation`, `diagnostics`, `doctor`
+- [Notifications & diagnostics](https://docs.kici.dev/user/cli/notifications-and-diagnostics/) — `notifications`, `verify-attestation`, `diagnostics`, `doctor`, `report`
 
 Each area page carries a `## Guide` section (worked examples and command-by-command narrative) and a `## Reference` section (the always-current generated signature list for that area's commands).
 
@@ -702,12 +707,13 @@ companion at [Operator troubleshooting](https://docs.kici.dev/operator/troublesh
 
 ## Fast triage
 
-| You see...                                                     | Jump to                                                 |
-| -------------------------------------------------------------- | ------------------------------------------------------- |
-| A run finishes with `No jobs dispatched`                       | [No jobs dispatched](https://docs.kici.dev/user/common-failures/#no-jobs-dispatched)               |
-| A run fails complaining the lock file is stale or incompatible | [Lock-file drift](https://docs.kici.dev/user/common-failures/#lock-file-drift)                     |
-| You pushed but no run ever appears                             | [The webhook never arrives](https://docs.kici.dev/user/common-failures/#the-webhook-never-arrives) |
-| A run is stuck "queued" and no agent ever picks it up          | [The agent won't connect](https://docs.kici.dev/user/common-failures/#the-agent-wont-connect)      |
+| You see...                                                     | Jump to                                                                             |
+| -------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| A run finishes with `No jobs dispatched`                       | [No jobs dispatched](https://docs.kici.dev/user/common-failures/#no-jobs-dispatched)                                           |
+| A run fails complaining the lock file is stale or incompatible | [Lock-file drift](https://docs.kici.dev/user/common-failures/#lock-file-drift)                                                 |
+| You pushed but no run ever appears                             | [The webhook never arrives](https://docs.kici.dev/user/common-failures/#the-webhook-never-arrives)                             |
+| A run is stuck "queued" and no agent ever picks it up          | [The agent won't connect](https://docs.kici.dev/user/common-failures/#the-agent-wont-connect)                                  |
+| A `commitMessage`-gated workflow stops running for some events | [A `commitMessage` filter never evaluates](https://docs.kici.dev/user/common-failures/#a-commitmessage-filter-never-evaluates) |
 
 ## No jobs dispatched
 
@@ -847,6 +853,24 @@ the unpullable image) — hand this to your operator with the run's failure reas
 The full provisioning-failure playbook is in
 [Operator troubleshooting](https://docs.kici.dev/operator/troubleshooting/).
 
+## A `commitMessage` filter never evaluates
+
+**Symptom.** A workflow gated on a `commitMessage` trigger filter stops running
+for some events, even though the message looks like it should match.
+
+**Cause.** The event carries no commit message. A branch-deletion push has no
+head commit, and a self-hosted forge (Gogs, or a GitLab source) may publish none
+at the configured path. The filter is **fail-visible**: when it cannot read a
+message, the workflow does not run rather than running ungated.
+
+**Diagnose.** The decision trace records the `commitMessage` check with the
+verdict `indeterminate` and the reason `no commit message in payload`. That is
+distinct from an `excluded` verdict, which the message itself caused.
+
+**Fix.** For a self-hosted forge, set the source's `commitMessage` payload path so
+the orchestrator can read the head commit's message. A branch-deletion push
+genuinely carries no message and is expected not to match.
+
 ## When to escalate to your operator
 
 The failures above are ones you can resolve from your workflow repo and the
@@ -1140,12 +1164,14 @@ Each workflow entry includes:
 | `concurrency`          | Workflow-level concurrency config: `hasGroup`, `cancelInProgress`, `max` (optional). See [concurrency groups](https://docs.kici.dev/user/concurrency/).                                                                                                                                                                                                                                                                                                                                  |
 | `timeout`              | Whole-run wall-clock timeout in milliseconds (optional). The orchestrator reads this at run creation to set the run deadline.                                                                                                                                                                                                                                                                                                                                   |
 | `approval`             | Normalized approval gate (optional): `clauses`, `reason`, `timeoutSeconds`, `when`. When present the whole run is held before any job is dispatched. Job and step entries carry the same normalized block for job- and step-level gates. See [approval gates](https://docs.kici.dev/user/approvals/).                                                                                                                                                                                    |
+| `hasFilter`            | `true` when the workflow declares a workflow-level `filter` predicate (optional; omitted rather than `false`). The predicate itself is never serialized — the flag tells the orchestrator an agent must evaluate the workflow before any of its jobs is dispatched. See [global workflows](https://docs.kici.dev/user/global-workflows/#narrowing-with-a-filter).                                                                                                                        |
 | Hook flags             | Boolean flags (`hasOnCancel`, `hasCleanup`, `hasOnSuccess`, `hasOnFailure`) indicating which lifecycle hooks are defined. Job entries additionally have `hasBeforeStep` and `hasAfterStep`.                                                                                                                                                                                                                                                                     |
 
 Step entries carry their own capability flags, so the orchestrator can reason about a step without loading your TypeScript:
 
 | Flag            | Meaning                                                                                                                                              |
 | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hasOutputs`    | The step declares an output schema, so the run has typed outputs to record for it. Present on every step entry.                                      |
 | `hasCheck`      | The step declares an idempotent `check` facet, so a run can be dispatched in check mode. See [idempotent steps and check mode](https://docs.kici.dev/user/idempotent-steps/). |
 | `hasWhenInSync` | The step declares a `whenInSync` facet that produces its outputs when `check` reports no drift.                                                      |
 | `hasRules`      | The step has conditional rules (evaluated agent-side).                                                                                               |
@@ -1767,7 +1793,7 @@ export const pushMain = fixture('push-main', {
 
 Source: https://docs.kici.dev/user/workflow-patterns/
 
-Practical patterns for building real-world KiCI workflows in TypeScript. The patterns are organised across five pages -- start with [Basic CI](https://docs.kici.dev/user/patterns/basic/) if you're new, or jump to [Integrations](https://docs.kici.dev/user/patterns/integrations/) if you're wiring up a non-GitHub forge or a generic webhook.
+Practical patterns for building real-world KiCI workflows in TypeScript. The patterns are organised across seven pages -- start with [Basic CI](https://docs.kici.dev/user/patterns/basic/) if you're new, or jump to [Integrations](https://docs.kici.dev/user/patterns/integrations/) if you're wiring up a non-GitHub forge or a generic webhook.
 
 | Page                                                       | Covers                                                                                                                                             |
 | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -1775,6 +1801,8 @@ Practical patterns for building real-world KiCI workflows in TypeScript. The pat
 | [Conditionals & matrix](https://docs.kici.dev/user/patterns/conditionals-matrix/) | Conditional execution with rules, matrix builds (static + dynamic), and dynamic job generation.                                                    |
 | [Integrations](https://docs.kici.dev/user/patterns/integrations/)                 | Workflow chaining, generic webhooks, Stripe handlers, self-hosted git forges (Forgejo / Gitea / Gogs), plain GitHub repo webhooks (no GitHub App). |
 | [Scheduling & events](https://docs.kici.dev/user/patterns/scheduling-and-events/) | Nightly cron, workflow-complete-triggered deploys, custom event chaining.                                                                          |
+| [Git credentials](https://docs.kici.dev/user/patterns/git-credentials/)           | Declaring named git credentials from the secrets backend, and pushing from a job (including to the job's own repository).                          |
+| [Host restart](https://docs.kici.dev/user/patterns/host-restart/)                 | `restartHost()` and `waitForHostAlive()` -- reboot the host a workflow runs on and resume in a second job pinned to the same host.                 |
 | [Pattern reference](https://docs.kici.dev/user/patterns/reference/)               | Step context, the examples repository, and GitHub check run output -- cross-cutting reference shared by every pattern above.                       |
 
 ## See also
@@ -2133,7 +2161,6 @@ Synopsis: `kici init [options]`
 | `--private-registry <url>`         |                        | Scaffold a workflow registries: entry pointing at <url>                                             |
 | `--private-registry-scope <scope>` |                        | Optional npm package scope (e.g. @my-org) for the private registry                                  |
 | `--private-registry-secret <ref>`  | `production:NPM_TOKEN` | Qualified secret reference (env:NAME) the private registry token comes from                         |
-| `--use-verdaccio-local`            | `false`                |                                                                                                     |
 
 ### `kici login`
 
@@ -2408,7 +2435,7 @@ Generate a fixture template for an event type. Useful for creating custom test p
 kici fixture <event> [options]
 ```
 
-**Valid events:** `pr:open`, `pr:sync`, `pr:close`, `pr:reopen`, `push`, `tag`, `comment`, `review`, `review_comment`, `release`, `dispatch`, `create`, `delete`, `status`, `workflow_run`, `fork`, `star`, `watch`, `kici_event`, `workflow_complete`, `job_complete`, `generic_webhook`, `schedule`, `lifecycle` (many support `:action` suffixes, e.g. `comment:edited`, `release:published`, `lifecycle:workflow_complete`). `webhook:<source>` is a shorthand alias for `generic_webhook:<source>`.
+**Valid events:** `pr:open`, `pr:sync`, `pr:close`, `pr:reopen`, `push`, `tag`, `comment`, `review`, `review_comment`, `release`, `dispatch`, `create`, `delete`, `status`, `workflow_run`, `fork`, `star`, `watch`, `kici_event`, `workflow_complete`, `workflows_failed_batch`, `job_complete`, `generic_webhook`, `schedule`, `lifecycle` (many support `:action` suffixes, e.g. `comment:edited`, `release:published`, `lifecycle:workflow_complete`). `webhook:<source>` is a shorthand alias for `generic_webhook:<source>`.
 
 **Examples:**
 
@@ -2438,7 +2465,7 @@ Generate TypeScript declaration files from orchestrator environment metadata. Th
 kici types [options]
 ```
 
-**Prerequisites:** Must be authenticated via `kici login`.
+**Prerequisites:** Authenticate via `kici login` to fetch the real key set. Without it, `kici types` writes an empty stub (see "Offline behavior" below).
 
 **Output:** `.kici/types/secrets.d.ts`
 
@@ -2460,7 +2487,9 @@ kici types --kici-dir packages/app/.kici
 
 After generating types, `ctx.secrets.get('MY_KEY')` and `ctx.secrets.expose('DB_HOST')` gain autocomplete and type checking in your IDE.
 
-**Git workflow:** Commit the generated `.kici/types/secrets.d.ts` so team members get type checking without needing orchestrator access. Run `kici types` to refresh when environments change.
+**Git workflow:** `.kici/types/secrets.d.ts` is a local development aid, not source — its content is a snapshot of one org's secret keys fetched from the Platform. `kici init` gitignores `.kici/types/`, so the file stays out of version control. Each team member runs `kici types` (or an authenticated `kici compile`) to generate their own copy. Do not commit it: a stale committed copy would type-check against secret keys that no longer exist.
+
+**Offline behavior:** When the Platform cannot be reached — not logged in, no active org, or offline — `kici types` never fails. If a `secrets.d.ts` already exists, `kici types` keeps it untouched, so a transient outage does not wipe your real key set. If the file is absent (a fresh clone or unauthenticated CI), `kici types` writes a valid empty stub. Type checking then degrades to "no known keys" (any key name is accepted) rather than breaking with "module has no exported member". Run `kici types` again once authenticated to refresh it.
 
 **Auto-regeneration:** `kici compile` automatically runs `kici types` after successful compilation when authenticated. See the [kici compile](https://docs.kici.dev/user/cli/authoring-and-local/#kici-compile) section for details.
 
@@ -2545,7 +2574,7 @@ kici docs llm sdk | claude -- "Read this and help me author a deploy workflow"
 kici docs llm --out kici-llms-index.txt
 ```
 
-Bundles are regenerated from `docs/` every time `@kici-dev/compiler` is built, so they always match your installed CLI version. The index lists each task bundle — `getting-started`, `sdk`, `sdk-runtime`, `cli`, `patterns`, `features`, `providers`, `architecture` — with its size and a one-line purpose; pass the bundle id as the topic. Every cross-reference link inside a bundle is an absolute `docs.kici.dev` URL. The same files are published online following the [llms.txt convention](https://llmstxt.org/).
+Bundles are regenerated from `docs/` every time `@kici-dev/compiler` is built, so they always match your installed CLI version. The index lists each task bundle — `getting-started`, `sdk`, `sdk-runtime`, `cli`, `patterns`, `features`, `features-execution`, `providers`, `architecture` — with its size and a one-line purpose; pass the bundle id as the topic. Every cross-reference link inside a bundle is an absolute `docs.kici.dev` URL. The same files are published online following the [llms.txt convention](https://llmstxt.org/).
 
 ## Reference
 
@@ -2943,9 +2972,9 @@ kici diagnostics --json
 Walk your KiCI setup end to end and print the exact next command for each
 problem found. Where `kici diagnostics` shows the org's infrastructure, `kici
 doctor` checks **your own setup**: it runs six checks in onboarding order —
-login (stored, unexpired credentials), active organization, a live token probe
-against the platform, a connected orchestrator for the org, a present, fresh,
-and committed lock file, and whether every workflow's `runsOn` labels are
+login (stored, unexpired credentials), active organization, a present, fresh,
+and committed lock file, a live token probe against the platform, a connected
+orchestrator for the org, and whether every workflow's `runsOn` labels are
 satisfiable by a connected agent or scaler. Each check reports pass/warn/fail
 with the fix command (e.g. `kici login`, `kici org use <name>`,
 `kici compile`), so the first failing row tells you exactly what to run next.
@@ -2967,6 +2996,60 @@ kici doctor --json
 The command exits `0` when every check passes, `1` when any check warns, and
 `2` when any check fails, so it also works as a CI preflight.
 
+### kici report
+
+Gather a diagnostic bundle to share when you report a problem. `kici doctor`
+tells you what is wrong; `kici report` packages the context somebody else needs
+to see it. The bundle holds your CLI, Node and orchestrator versions, your
+redacted configuration, and your project's workflow and lock-file state. With
+`--run` it also holds the failing run's detail and logs.
+
+```bash
+kici report [options]
+```
+
+The command writes a ZIP and prints its path and `sha256`. It does not send
+anything. Open the file and read it before you share it.
+
+```bash
+# Bundle your setup
+kici report
+
+# Scope it to the run that failed, and say what went wrong
+kici report --run 8f3c1d2e --message "matrix job hangs on macOS"
+
+# Choose the output path and attach your own metadata
+kici report -o /tmp/bug.zip --metadata ticket=1234 --metadata severity=high
+```
+
+**Redaction.** KiCI removes known secret shapes — API keys, tokens, `Authorization`
+headers, private keys, passwords in connection URLs — from configuration and
+from log text. This is best effort. A secret in a format KiCI does not
+recognize can survive, so review the bundle before you share it. `--no-redact`
+turns redaction off and prints a warning; use it only on a bundle you keep.
+
+**Sending it privately.** Add `--upload` to send the bundle to KiCI over a
+one-time upload link. The bundle goes straight to KiCI storage, and the command
+prints a reference id to quote:
+
+```bash
+kici report --run 8f3c1d2e --upload --message "matrix job hangs on macOS"
+```
+
+Uploads are private, are kept for 90 days, and are yours to withdraw:
+
+```bash
+# See what you have sent
+kici report list
+
+# Delete an uploaded bundle
+kici report withdraw <ref>
+```
+
+Anyone in your organization can upload a report. By default you see and
+withdraw your own; a member with the `support:admin` permission can manage
+every report in the organization.
+
 ## Reference
 
 <!-- BEGIN GENERATED: kici-notifications-and-diagnostics (do not edit; run the doc generator) -->
@@ -3174,6 +3257,49 @@ Synopsis: `kici notifications subscriptions remove <id> [options]`
 | ------------ | ------- | ---------------------------------------------- |
 | `--org <id>` |         | Target organization (overrides the active org) |
 
+### `kici report`
+
+Gather a redacted diagnostic bundle to share when reporting an issue
+
+Synopsis: `kici report [options]`
+
+**Options**
+
+| Option                   | Default | Description                                                  |
+| ------------------------ | ------- | ------------------------------------------------------------ |
+| `--run <id>`             |         | Scope the bundle to a failing run                            |
+| `-o, --output <path>`    |         | Where to write the bundle ZIP                                |
+| `--metadata <key=value>` |         | Attach metadata (repeatable)                                 |
+| `--no-redact`            |         | Do NOT redact secrets (prints a loud warning)                |
+| `--upload`               |         | Upload the bundle privately to KiCI and print a reference id |
+| `--message <text>`       |         | Describe the problem (sent with --upload)                    |
+| `--email <address>`      |         | Contact address for follow-up (sent with --upload)           |
+| `--kici-dir <path>`      | `.kici` | Path to the .kici directory                                  |
+
+### `kici report list`
+
+List the issue reports you have uploaded
+
+Synopsis: `kici report list [options]`
+
+**Options**
+
+| Option   | Default | Description     |
+| -------- | ------- | --------------- |
+| `--json` | `false` | Output raw JSON |
+
+### `kici report withdraw`
+
+Withdraw an uploaded report and delete its bundle
+
+Synopsis: `kici report withdraw <ref>`
+
+**Arguments**
+
+| Argument | Required | Variadic | Description                            |
+| -------- | -------- | -------- | -------------------------------------- |
+| `ref`    | yes      | no       | Reference id of the report to withdraw |
+
 ### `kici verify-attestation`
 
 Verify a KiCI provenance attestation bundle offline
@@ -3489,7 +3615,11 @@ kici runs list --json | jq '.runs[].runId'
 #### kici runs show
 
 Show a run's summary header plus its jobs-and-steps tree (name, status,
-duration, exit code). If the run id is not on the Platform but exists in your
+duration, exit code). A run that never started a step also prints why: the
+run-level failure, and per job the reason it did not run — a job a
+[context](https://docs.kici.dev/user/contexts/#protection-rules) rejected names the context and the
+rule. Any approval hold on the run is listed too, with its context, hold type,
+status and reason. If the run id is not on the Platform but exists in your
 local run history (from `kici run <event> --local`), the local record is shown instead.
 
 ```bash
@@ -3670,10 +3800,12 @@ Synopsis: `kici approve <run-id> [options]`
 
 **Options**
 
-| Option           | Default | Description                                 |
-| ---------------- | ------- | ------------------------------------------- |
-| `--job <name>`   |         | Approve the hold for a specific job         |
-| `--step <index>` |         | Approve a step-scoped hold (requires --job) |
+| Option               | Default | Description                                                                                  |
+| -------------------- | ------- | -------------------------------------------------------------------------------------------- |
+| `--job <name>`       |         | Approve the hold for a specific job                                                          |
+| `--step <index>`     |         | Approve a step-scoped hold (requires --job)                                                  |
+| `--hold-type <type>` |         | Approve the hold of this type (reviewer, timer, concurrency, security) — a job can carry two |
+| `--hold <id>`        |         | Approve one hold by its id, as listed when nothing else separates them                       |
 
 ### `kici reject`
 
@@ -3689,11 +3821,13 @@ Synopsis: `kici reject <run-id> [options]`
 
 **Options**
 
-| Option            | Default | Description                                |
-| ----------------- | ------- | ------------------------------------------ |
-| `--job <name>`    |         | Reject the hold for a specific job         |
-| `--step <index>`  |         | Reject a step-scoped hold (requires --job) |
-| `--reason <text>` |         | Reason for the rejection                   |
+| Option               | Default | Description                                                                                 |
+| -------------------- | ------- | ------------------------------------------------------------------------------------------- |
+| `--job <name>`       |         | Reject the hold for a specific job                                                          |
+| `--step <index>`     |         | Reject a step-scoped hold (requires --job)                                                  |
+| `--hold-type <type>` |         | Reject the hold of this type (reviewer, timer, concurrency, security) — a job can carry two |
+| `--hold <id>`        |         | Reject one hold by its id, as listed when nothing else separates them                       |
+| `--reason <text>`    |         | Reason for the rejection                                                                    |
 
 ### `kici run`
 
@@ -3891,7 +4025,7 @@ Synopsis: `kici runs rerun <run-id> [options]`
 
 ### `kici runs show`
 
-Show a run summary with its jobs and steps
+Show a run summary with its jobs and steps, why a job did not run, and any approval hold
 
 Synopsis: `kici runs show <run-id> [options]`