@kici-dev/compiler 0.4.0 → 0.5.0

package/dist/cli.js

@@ -7,7 +7,7 @@ import { realpathSync } from "node:fs";
 import { Argument, Command, Option } from "commander";
 import pc from "picocolors";
 //#region src/cli.ts
-const version = "0.4.0";
+const version = "0.5.0";
 /**
 * Top-level commands that were removed, mapped to their current equivalent.
 * Consulted when the CLI hits an unknown command so the user gets a precise

package/dist/commands/compile.js

@@ -1,5 +1,5 @@
 import "../rolldown-runtime-ClRpJifh.js";
-import { PURITY_FALLBACK_CODE, compilerError, formatError, isCompilerError } from "../errors/formatter.js";
+import { formatError, isCompilerError } from "../errors/formatter.js";
 import "../errors/index.js";
 import { discoverWorkflows, resolveKiciDir } from "../execution/executor.js";
 import "../execution/index.js";
@@ -8,7 +8,6 @@ import { runTypecheck } from "../validation/typecheck.js";
 import "../validation/index.js";
 import { BREAKING_FLOOR, SCHEMA_VERSION } from "../types.js";
 import { computeLockfileHash, detectGitRoot, generateLockFile, schemaWindowWarning, serializeLockFile } from "../lockfile/generator.js";
-import { collectWorkflowPurityWarnings } from "../lockfile/purity-diagnostics.js";
 import "../lockfile/index.js";
 import path from "node:path";
 import { existsSync } from "node:fs";
@@ -19,16 +18,6 @@ import { PackageManager, detectPackageManagerSync } from "@kici-dev/core/package
 import { execSync } from "node:child_process";
 //#region src/commands/compile.ts
 /**
-* Render an impure dynamic-value function as a `W101` compile warning naming the
-* job, the field, the impurity reason, and the ~5-10s agent-side init-job cost.
-*/
-function formatPurityWarning(w) {
-	return formatError(compilerError(PURITY_FALLBACK_CODE, `job "${w.jobName}": ${w.field} function is not pure (${w.reason}). An init job will be required, adding ~5-10s delay.`, {
-		severity: "warning",
-		suggestion: `Make the ${w.field} function pure (synchronous, referencing only its parameters) to inline it and skip the init job. See https://docs.kici.dev — dynamic values.`
-	}));
-}
-/**
 * Read the existing lock file and return its lockfileHash, if present.
 */
 async function readExistingLockfileHash(lockPath) {
@@ -87,7 +76,6 @@ async function compileCommand(options) {
 		}
 		if (options.verbose) logger.debug(pc.dim("Validation passed"));
 		const lockJson = serializeLockFile(generateLockFile(workflowsWithSource));
-		for (const warning of collectWorkflowPurityWarnings(workflowsWithSource)) logger.warn(formatPurityWarning(warning));
 		const windowWarning = schemaWindowWarning(BREAKING_FLOOR, SCHEMA_VERSION);
 		if (windowWarning) logger.warn(pc.yellow(windowWarning));
 		if (!options.check) {

package/dist/commands/preview.js

@@ -2,8 +2,6 @@ import "../rolldown-runtime-ClRpJifh.js";
 import { discoverWorkflows, resolveKiciDir } from "../execution/executor.js";
 import "../execution/index.js";
 import { transformTriggers } from "../lockfile/generator.js";
-import { analyzeJobPurity } from "../lockfile/purity-diagnostics.js";
-import "../lockfile/index.js";
 import { displayDryRun } from "../test-runner/dry-run.js";
 import { parseEventArg } from "../test-runner/event-types.js";
 import { buildEventPayload } from "../test-runner/payload-builder.js";
@@ -90,15 +88,10 @@ async function previewEvent(event, options) {
 				return false;
 			}
 		}
-		const purityWarnings = [];
-		for (const w of workflows) for (const j of w.jobs) {
-			if (typeof j === "function") continue;
-			purityWarnings.push(...analyzeJobPurity(j, w.name));
-		}
 		displayDryRun(lockWorkflows, decisions, {
 			workflow: options.workflow,
 			job: options.job
-		}, purityWarnings);
+		});
 		return true;
 	} catch (error) {
 		const message = toErrorMessage(error);

package/dist/commands/types.js

@@ -25,8 +25,7 @@ async function typesCommand(options = {}) {
 				name: e.name,
 				keys: e.secretKeys ?? []
 			})),
-			endpoint: (config.platformEndpoint ?? config.endpoint ?? "kici Platform").replace(/\/+$/, ""),
-			generatedAt: /* @__PURE__ */ new Date()
+			endpoint: (config.platformEndpoint ?? config.endpoint ?? "kici Platform").replace(/\/+$/, "")
 		});
 		const kiciDir = options.kiciDir ?? ".kici";
 		const typesDir = path.join(kiciDir, "types");

package/dist/errors/formatter.d.ts

@@ -1,7 +1,7 @@
 /**
  * Error code string. Thrown compile errors use `E<digits>` (e.g. 'E001', 'E102');
- * advisory, render-only diagnostics use `W<digits>` (e.g. 'W101'). `isCompilerError`
- * only matches the `E<digits>` family — warning codes are never thrown, only rendered.
+ * advisory, render-only diagnostics use `W<digits>`. `isCompilerError` only
+ * matches the `E<digits>` family — warning codes are never thrown, only rendered.
  */
 type ErrorCode = string;
 /** Diagnostic severity. Errors abort compilation; warnings are advisory (compile still succeeds). */
@@ -9,8 +9,6 @@ export declare enum DiagnosticSeverity {
     Error = "error",
     Warning = "warning"
 }
-/** Warning code for the impure dynamic-value → init-job fallback. */
-export declare const PURITY_FALLBACK_CODE = "W101";
 /** Source location for error reporting */
 export interface SourceLocation {
     readonly file: string;

package/dist/errors/formatter.js

@@ -7,8 +7,6 @@ let DiagnosticSeverity = /* @__PURE__ */ function(DiagnosticSeverity) {
 	DiagnosticSeverity["Warning"] = "warning";
 	return DiagnosticSeverity;
 }({});
-/** Warning code for the impure dynamic-value → init-job fallback. */
-const PURITY_FALLBACK_CODE = "W101";
 /**
 * Format error in GNU standard format: file:line:column: error [CODE]: message
 *
@@ -40,6 +38,6 @@ function isCompilerError(error) {
 	return typeof error === "object" && error !== null && "code" in error && "message" in error && typeof error.code === "string" && /^E\d+$/.test(error.code);
 }
 //#endregion
-export { DiagnosticSeverity, PURITY_FALLBACK_CODE, compilerError, formatError, isCompilerError };
+export { DiagnosticSeverity, compilerError, formatError, isCompilerError };
 
 //# sourceMappingURL=formatter.js.map

package/dist/errors/index.d.ts

@@ -1,4 +1,4 @@
-export { formatError, compilerError, isCompilerError, DiagnosticSeverity, PURITY_FALLBACK_CODE, } from './formatter.js';
+export { formatError, compilerError, isCompilerError, DiagnosticSeverity } from './formatter.js';
 export type { SourceLocation, CompilerError } from './formatter.js';
 export { CapabilityGapError, formatCapabilityGapError } from './capability-gap.js';
 export type { CapabilityGapInfo } from './capability-gap.js';

package/dist/errors/index.js

@@ -1,5 +1,5 @@
 import "../rolldown-runtime-ClRpJifh.js";
-import { DiagnosticSeverity, PURITY_FALLBACK_CODE, compilerError, formatError, isCompilerError } from "./formatter.js";
+import { DiagnosticSeverity, compilerError, formatError, isCompilerError } from "./formatter.js";
 import { CapabilityGapError, formatCapabilityGapError } from "./capability-gap.js";
 import { firstStepLocation, locationForJob, locationForWorkflow } from "./source-location.js";
-export { CapabilityGapError, DiagnosticSeverity, PURITY_FALLBACK_CODE, compilerError, firstStepLocation, formatCapabilityGapError, formatError, isCompilerError, locationForJob, locationForWorkflow };
+export { CapabilityGapError, DiagnosticSeverity, compilerError, firstStepLocation, formatCapabilityGapError, formatError, isCompilerError, locationForJob, locationForWorkflow };

package/dist/generators/secrets-dts.d.ts

@@ -13,7 +13,6 @@ export interface ContextMetadata {
 interface GenerateSecretsDtsOptions {
     contexts: ContextMetadata[];
     endpoint: string;
-    generatedAt: Date;
 }
 /**
  * Generate a .d.ts string from context metadata.

package/dist/generators/secrets-dts.js

@@ -34,11 +34,10 @@ function buildKeySourceMap(contexts) {
 * @returns The .d.ts file content as a string
 */
 function generateSecretsDts(options) {
-	const { contexts, endpoint, generatedAt } = options;
+	const { contexts, endpoint } = options;
 	const lines = [];
 	lines.push("// @generated by kici types -- DO NOT EDIT");
 	lines.push(`// Source: ${endpoint}`);
-	lines.push(`// Generated: ${generatedAt.toISOString()}`);
 	lines.push("// Run `kici types` to refresh");
 	lines.push("");
 	lines.push("declare module '@kici-dev/sdk' {");

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

@@ -313,12 +313,13 @@ 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 GitHub App source populates all eight -- though the file-contents capability arrives as a per-delivery factory rather than a prebuilt instance, because a GitHub client is scoped to one installation and the installation id is only known once the delivery's credentials are resolved. 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.
 
 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 +407,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
 
@@ -525,7 +527,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 +586,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 34.
 - **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
@@ -829,7 +831,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 +844,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 +1230,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
@@ -1320,7 +1329,7 @@ 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, ContributorResolver, CheckStatusPoster)
 - Trigger matching engine (branch, path, event evaluation)
 - 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)
@@ -1336,11 +1345,16 @@ Shared business logic used by all three tiers. Single source of truth for cross-
 - 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-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`)
 - 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/`
@@ -1464,7 +1478,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

@@ -702,12 +702,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 +848,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,6 +1159,7 @@ 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: