@kici-dev/engine 0.1.22 → 0.1.24

package/dist/approval/types.d.ts

@@ -22,8 +22,8 @@ export type ApproverClause = z.infer<typeof approverClauseSchema>;
 /** Granularity of a held element. */
 export declare const HoldScope: z.ZodEnum<{
     job: "job";
-    step: "step";
     workflow: "workflow";
+    step: "step";
 }>;
 export type HoldScope = z.infer<typeof HoldScope>;
 /** What triggered the hold: an environment policy (mandatory) or SDK code (explicit). */

package/dist/audit/access-log-policy.d.ts

@@ -11,7 +11,10 @@
  * 1. `outcome !== 'allowed'` → always record (denied/error are full-fidelity).
  * 2. `actor.type === 'platform_operator'` → always record (compliance: any
  *    activity by a non-org member must be auditable in full).
- * 3. The per-action `POLICY_BY_ACTION` decision (`always` / `sample` /
+ * 3. agent-attributed actor (`actor.agent` present) → always record. The
+ *    agent-provenance guarantee is that every action an agent takes is fully
+ *    auditable; a sampled subset would break it.
+ * 4. The per-action `POLICY_BY_ACTION` decision (`always` / `sample` /
  *    `rate_limit`).
  *
  * Browser-safe: this module MUST NOT import any Node built-ins (`node:crypto`

package/dist/audit/access-log-policy.js

@@ -14,7 +14,10 @@ import { z } from "zod";
 * 1. `outcome !== 'allowed'` → always record (denied/error are full-fidelity).
 * 2. `actor.type === 'platform_operator'` → always record (compliance: any
 *    activity by a non-org member must be auditable in full).
-* 3. The per-action `POLICY_BY_ACTION` decision (`always` / `sample` /
+* 3. agent-attributed actor (`actor.agent` present) → always record. The
+*    agent-provenance guarantee is that every action an agent takes is fully
+*    auditable; a sampled subset would break it.
+* 4. The per-action `POLICY_BY_ACTION` decision (`always` / `sample` /
 *    `rate_limit`).
 *
 * Browser-safe: this module MUST NOT import any Node built-ins (`node:crypto`
@@ -38,6 +41,10 @@ const POLICY_BY_ACTION = {
 		kind: "sample",
 		allowedRate: .05
 	},
+	"run.structured.read": {
+		kind: "sample",
+		allowedRate: .05
+	},
 	"runs.list.read": {
 		kind: "sample",
 		allowedRate: .05
@@ -152,6 +159,8 @@ const POLICY_BY_ACTION = {
 	"backend.test": { kind: "always" },
 	"fleet.host.declare": { kind: "always" },
 	"fleet.host.remove": { kind: "always" },
+	"fleet.init_runner.bringup": { kind: "always" },
+	"fleet.pre_boot.send": { kind: "always" },
 	"global_workflows.update": { kind: "always" },
 	"org_settings.dashboard_write_policy.update": { kind: "always" },
 	"cluster_name.update": { kind: "always" },
@@ -204,6 +213,7 @@ function actorKey(actor) {
 function shouldRecordAccess(action, outcome, actor, requestId, limiter) {
 	if (outcome !== "allowed") return true;
 	if (actor.type === "platform_operator") return true;
+	if (actor.type === "user" && actor.agent) return true;
 	const policy = POLICY_BY_ACTION[action];
 	switch (policy.kind) {
 		case "always": return true;

package/dist/audit/activity.d.ts

@@ -16,7 +16,7 @@
 import { z } from 'zod';
 /**
  * Source discriminator on a unified Activity row.
- * NOT to be confused with `AccessLogSource` (platform_proxy / admin_http /
+ * NOT to be confused with `AccessLogSource` (platform_proxy / admin_http / agent /
  * admin_cli) — that field is renamed to `origin` on the unified row to
  * avoid the collision.
  */
@@ -73,6 +73,7 @@ export declare const activityRowSchema: z.ZodObject<{
     details: z.ZodNullable<z.ZodUnknown>;
     requestId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     origin: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        agent: "agent";
         platform_proxy: "platform_proxy";
         admin_http: "admin_http";
         admin_cli: "admin_cli";
@@ -105,6 +106,7 @@ export declare const activityFilterSchema: z.ZodObject<{
         denied: "denied";
     }>>;
     origin: z.ZodOptional<z.ZodEnum<{
+        agent: "agent";
         platform_proxy: "platform_proxy";
         admin_http: "admin_http";
         admin_cli: "admin_cli";

package/dist/audit/activity.js

@@ -1,6 +1,6 @@
 import "../chunk-BTugEXQM.js";
 import { ActorType } from "../protocol/messages/actor.js";
-import { AccessLogOutcome } from "../protocol/messages/access-log.js";
+import { AccessLogOutcome, AccessLogSource } from "../protocol/messages/access-log.js";
 import { z } from "zod";
 //#region src/audit/activity.ts
 /**
@@ -20,7 +20,7 @@ import { z } from "zod";
 */
 /**
 * Source discriminator on a unified Activity row.
-* NOT to be confused with `AccessLogSource` (platform_proxy / admin_http /
+* NOT to be confused with `AccessLogSource` (platform_proxy / admin_http / agent /
 * admin_cli) — that field is renamed to `origin` on the unified row to
 * avoid the collision.
 */
@@ -71,16 +71,12 @@ const activityRowSchema = z.object({
 	/** access_log only — request correlation ID. */
 	requestId: z.string().nullable().optional(),
 	/**
-	* access_log only — origin of the entry (platform_proxy / admin_http /
-	* admin_cli). Renamed from `source` on the access_log row schema so the
-	* unified row's `source` field is unambiguously the audit_log vs.
-	* access_log discriminator.
+	* access_log only — origin of the entry (the AccessLogSource values:
+	* platform_proxy / admin_http / admin_cli / agent). Renamed from `source` on
+	* the access_log row schema so the unified row's `source` field is
+	* unambiguously the audit_log vs. access_log discriminator.
 	*/
-	origin: z.enum([
-		"platform_proxy",
-		"admin_http",
-		"admin_cli"
-	]).nullable().optional()
+	origin: AccessLogSource.nullable().optional()
 });
 /**
 * Unified filter schema accepted by GET /orgs/:customerId/activity.
@@ -94,11 +90,7 @@ const activityFilterSchema = z.object({
 	/** Free-form: matches access_log AccessLogAction values OR audit_log free-form actions. */
 	action: z.string().optional(),
 	outcome: AccessLogOutcome.optional(),
-	origin: z.enum([
-		"platform_proxy",
-		"admin_http",
-		"admin_cli"
-	]).optional(),
+	origin: AccessLogSource.optional(),
 	targetType: z.string().optional(),
 	targetId: z.string().optional(),
 	/** Sugar: maps to targetType='run' + targetId=runId. Both halves of the federation respect it. */

package/dist/audit/retention-policy.js

@@ -13,6 +13,7 @@ import "../chunk-BTugEXQM.js";
 */
 const ACCESS_LOG_WARM_DAYS = {
 	"run.detail.read": 30,
+	"run.structured.read": 30,
 	"runs.list.read": 30,
 	"runs.filters.read": 30,
 	"sources.list.read": 30,
@@ -65,6 +66,8 @@ const ACCESS_LOG_WARM_DAYS = {
 	"backend.test": 180,
 	"fleet.host.declare": 180,
 	"fleet.host.remove": 180,
+	"fleet.init_runner.bringup": 180,
+	"fleet.pre_boot.send": 180,
 	"global_workflows.update": 180,
 	"org_settings.dashboard_write_policy.update": 180,
 	"cluster_name.update": 180,
@@ -255,6 +258,7 @@ function secretAuditLogWarmSqlCase() {
 */
 const ACCESS_LOG_COLD_DAYS = {
 	"run.detail.read": 180,
+	"run.structured.read": 180,
 	"runs.list.read": 180,
 	"runs.filters.read": 180,
 	"sources.list.read": 180,
@@ -307,6 +311,8 @@ const ACCESS_LOG_COLD_DAYS = {
 	"backend.test": 730,
 	"fleet.host.declare": 730,
 	"fleet.host.remove": 730,
+	"fleet.init_runner.bringup": 730,
+	"fleet.pre_boot.send": 730,
 	"global_workflows.update": 730,
 	"org_settings.dashboard_write_policy.update": 730,
 	"cluster_name.update": 730,

package/dist/environment/host-match.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Identity facts of a single fan-out child, matched against a binding's
+ * `host_pattern`. `agentId` / `host` are the stable dispatch identity; `labels`
+ * is the host's label set. The union of all three is the match target.
+ */
+export interface HostFacts {
+    agentId: string;
+    host: string;
+    labels: readonly string[];
+}
+/**
+ * Whether a fan-out child's identity facts satisfy a binding's `host_pattern`.
+ *
+ * `'**'` / empty matches every host. Otherwise the pattern is compiled once
+ * (exact / glob / regex, same selector grammar as `runsOnAll`) and tested
+ * against the union `[agentId, host, ...labels]` — true if any element matches.
+ */
+export declare function matchHostPattern(facts: HostFacts, pattern: string): boolean;
+/**
+ * Rank a `host_pattern` by specificity for precedence: an exact literal (2)
+ * beats a glob/regex (1), which beats `'**'`/empty (0). Used to let a per-host
+ * binding override a fleet-wide one on a key collision.
+ */
+export declare function hostSpecificity(pattern: string): number;
+//# sourceMappingURL=host-match.d.ts.map

package/dist/environment/host-match.js

@@ -0,0 +1,67 @@
+import "../chunk-BTugEXQM.js";
+import { matcherMatches } from "../labels-match.js";
+import { assertSafeRegex, toLabelMatcher } from "../labels/compile.js";
+//#region src/environment/host-match.ts
+/** `'**'`, empty, or absent means "matches every host". */
+function matchesAllHosts(pattern) {
+	return pattern === "" || pattern === "**";
+}
+/** True when `pattern` is the `/source/flags` regex-string convention. */
+function asRegexString(pattern) {
+	if (pattern.length < 2 || !pattern.startsWith("/")) return null;
+	const lastSlash = pattern.lastIndexOf("/");
+	if (lastSlash === 0) return null;
+	return {
+		source: pattern.slice(1, lastSlash),
+		flags: pattern.slice(lastSlash + 1)
+	};
+}
+/**
+* Compile a `host_pattern` string into a `LabelMatcher`.
+*
+* - `/source/flags` → regex matcher (ReDoS-gated).
+* - a glob (picomatch-detected) → regex matcher.
+* - any other string → exact matcher.
+*/
+function compileHostPattern(pattern) {
+	const re = asRegexString(pattern);
+	if (re) {
+		assertSafeRegex(re.source, re.flags, `host_pattern /${re.source}/${re.flags}`);
+		return {
+			kind: "regex",
+			source: re.source,
+			flags: re.flags
+		};
+	}
+	return toLabelMatcher(pattern, `host_pattern '${pattern}'`);
+}
+/**
+* Whether a fan-out child's identity facts satisfy a binding's `host_pattern`.
+*
+* `'**'` / empty matches every host. Otherwise the pattern is compiled once
+* (exact / glob / regex, same selector grammar as `runsOnAll`) and tested
+* against the union `[agentId, host, ...labels]` — true if any element matches.
+*/
+function matchHostPattern(facts, pattern) {
+	if (matchesAllHosts(pattern)) return true;
+	const matcher = compileHostPattern(pattern);
+	return [
+		facts.agentId,
+		facts.host,
+		...facts.labels
+	].some((c) => matcherMatches(matcher, c));
+}
+/**
+* Rank a `host_pattern` by specificity for precedence: an exact literal (2)
+* beats a glob/regex (1), which beats `'**'`/empty (0). Used to let a per-host
+* binding override a fleet-wide one on a key collision.
+*/
+function hostSpecificity(pattern) {
+	if (matchesAllHosts(pattern)) return 0;
+	if (asRegexString(pattern)) return 1;
+	return toLabelMatcher(pattern, `host_pattern '${pattern}'`).kind === "regex" ? 1 : 2;
+}
+//#endregion
+export { hostSpecificity, matchHostPattern };
+
+//# sourceMappingURL=host-match.js.map

package/dist/environment/index.d.ts

@@ -1,3 +1,6 @@
 export type { Environment, EnvironmentBinding, EnvironmentVariable, EnvironmentSourceOverride, ScopedSecret, HeldRun, ProtectionGateResult, TrustTier, } from './types.js';
+export { TrustTierSchema } from './types.js';
 export { resolveSecretsForEnvironment, matchScopePattern, stripScopePrefix, } from './scope-resolver.js';
+export type { HostFacts } from './host-match.js';
+export { mergeOrderedMaps, EnvGateRejectReason } from './multi-env.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/environment/index.js

@@ -1,3 +1,5 @@
 import "../chunk-BTugEXQM.js";
+import { TrustTierSchema } from "./types.js";
 import { matchScopePattern, resolveSecretsForEnvironment, stripScopePrefix } from "./scope-resolver.js";
-export { matchScopePattern, resolveSecretsForEnvironment, stripScopePrefix };
+import { EnvGateRejectReason, mergeOrderedMaps } from "./multi-env.js";
+export { EnvGateRejectReason, TrustTierSchema, matchScopePattern, mergeOrderedMaps, resolveSecretsForEnvironment, stripScopePrefix };

package/dist/environment/multi-env.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Multi-environment merge helpers shared across the orchestrator dispatch path.
+ *
+ * A job may bind several deployment environments in order; their resolved
+ * secrets/variables are folded last-wins (a later environment's key overrides an
+ * earlier one) and their protection gates combine all-must-pass. This module is
+ * browser-safe (pure functions + a Zod enum, no Node built-ins) so it can be
+ * exported from the engine environment barrel.
+ */
+import { z } from 'zod';
+/**
+ * Reason a single bound environment rejects a run under all-must-pass
+ * aggregation. Used to name which environment and which rule blocked dispatch.
+ */
+export declare const EnvGateRejectReason: z.ZodEnum<{
+    branch_restricted: "branch_restricted";
+    trigger_filtered: "trigger_filtered";
+    repo_unmatched: "repo_unmatched";
+    trust_too_low: "trust_too_low";
+    env_disabled: "env_disabled";
+    env_not_found: "env_not_found";
+}>;
+export type EnvGateRejectReason = z.infer<typeof EnvGateRejectReason>;
+/**
+ * Fold an ordered list of per-environment resolved maps into one. Later entries
+ * override earlier keys (last-wins), matching the documented merge order for
+ * `environments: [...]`.
+ */
+export declare function mergeOrderedMaps(maps: ReadonlyArray<Record<string, string>>): Record<string, string>;
+//# sourceMappingURL=multi-env.d.ts.map

package/dist/environment/multi-env.js

@@ -0,0 +1,38 @@
+import "../chunk-BTugEXQM.js";
+import { z } from "zod";
+//#region src/environment/multi-env.ts
+/**
+* Multi-environment merge helpers shared across the orchestrator dispatch path.
+*
+* A job may bind several deployment environments in order; their resolved
+* secrets/variables are folded last-wins (a later environment's key overrides an
+* earlier one) and their protection gates combine all-must-pass. This module is
+* browser-safe (pure functions + a Zod enum, no Node built-ins) so it can be
+* exported from the engine environment barrel.
+*/
+/**
+* Reason a single bound environment rejects a run under all-must-pass
+* aggregation. Used to name which environment and which rule blocked dispatch.
+*/
+const EnvGateRejectReason = z.enum([
+	"branch_restricted",
+	"trigger_filtered",
+	"repo_unmatched",
+	"trust_too_low",
+	"env_disabled",
+	"env_not_found"
+]);
+/**
+* Fold an ordered list of per-environment resolved maps into one. Later entries
+* override earlier keys (last-wins), matching the documented merge order for
+* `environments: [...]`.
+*/
+function mergeOrderedMaps(maps) {
+	const out = {};
+	for (const m of maps) Object.assign(out, m);
+	return out;
+}
+//#endregion
+export { EnvGateRejectReason, mergeOrderedMaps };
+
+//# sourceMappingURL=multi-env.js.map

package/dist/environment/scope-resolver.d.ts

@@ -1,4 +1,6 @@
 import type { EnvironmentBinding, ScopedSecret } from './types.js';
+import { type HostFacts } from './host-match.js';
+export type { HostFacts } from './host-match.js';
 /**
  * Check whether a scope string matches a pattern.
  *
@@ -22,14 +24,23 @@ export declare function stripScopePrefix(scope: string): string;
  * Resolve secrets for an environment by matching bindings against scoped secrets.
  *
  * Takes already-filtered bindings (for the target environment). For each binding,
- * finds secrets whose scope matches the binding's scopePattern via picomatch.
- * When multiple scopes provide the same key, longest scope path wins (higher specificity).
- * Scope depth is computed AFTER stripping the backend prefix.
+ * finds secrets whose (substituted) scope matches the binding's scopePattern via
+ * picomatch. When multiple scopes provide the same key, precedence is the tuple
+ * `(host specificity, scope depth)` — a per-host binding (exact host) overrides a
+ * fleet-wide one, then longest scope path wins. Scope depth is computed AFTER
+ * stripping the backend prefix.
+ *
+ * When `hostFacts` is supplied (a fan-out child's identity), each binding is
+ * gated by its `host_pattern` and its `scope_pattern` is templated per-child
+ * (`${agentId}`/`${host}`/`${label:NAME}`). When omitted, only fleet-wide
+ * (`'**'`/NULL) non-templated bindings contribute — preserving the workflow-level
+ * (no-host) behaviour.
  *
  * @param bindings - Bindings already filtered for the target environment
  * @param allSecrets - All scoped secrets in the org
  * @param decryptFn - Pure decryption function (keeps this module crypto-free)
+ * @param hostFacts - Optional fan-out child identity for per-host resolution
  * @returns Flat record of decrypted secret key-value pairs
  */
-export declare function resolveSecretsForEnvironment(bindings: EnvironmentBinding[], allSecrets: ScopedSecret[], decryptFn: (s: ScopedSecret) => string): Record<string, string>;
+export declare function resolveSecretsForEnvironment(bindings: EnvironmentBinding[], allSecrets: ScopedSecret[], decryptFn: (s: ScopedSecret) => string, hostFacts?: HostFacts): Record<string, string>;
 //# sourceMappingURL=scope-resolver.d.ts.map

package/dist/environment/scope-resolver.js

@@ -1,4 +1,6 @@
 import "../chunk-BTugEXQM.js";
+import { hostSpecificity, matchHostPattern } from "./host-match.js";
+import { substituteScopePattern } from "./scope-template.js";
 import picomatch from "picomatch";
 //#region src/environment/scope-resolver.ts
 /**
@@ -41,31 +43,69 @@ function stripScopePrefix(scope) {
 	return colonIdx >= 0 ? scope.slice(colonIdx + 1) : scope;
 }
 /**
+* Resolve the effective scope pattern a binding contributes for a given host,
+* applying the host gate and per-child scope-pattern templating.
+*
+* Returns the (possibly substituted) scope pattern to glob-match secrets
+* against, or `null` when the binding contributes nothing for this host:
+* - With `hostFacts`: skipped when `host_pattern` doesn't match, or when a
+*   templated `scope_pattern` can't be substituted (missing label / unsafe
+*   value).
+* - Without `hostFacts` (workflow-level, no-host caller): only `'**'`/NULL
+*   host bindings contribute, and a templated `scope_pattern` is skipped (it
+*   cannot be substituted without facts).
+*/
+function bindingScopeForHost(binding, hostFacts) {
+	if (hostFacts) {
+		if (!matchHostPattern(hostFacts, binding.hostPattern)) return null;
+		return substituteScopePattern(binding.scopePattern, hostFacts);
+	}
+	if (binding.hostPattern !== "**" && binding.hostPattern !== "") return null;
+	return binding.scopePattern.includes("${") ? null : binding.scopePattern;
+}
+/** Higher `(hostSpec, scopeDepth)` wins; ties keep the first-encountered. */
+function candidateWins(c, existing) {
+	if (!existing) return true;
+	if (c.hostSpec !== existing.hostSpec) return c.hostSpec > existing.hostSpec;
+	return c.scopeDepth > existing.scopeDepth;
+}
+/**
 * Resolve secrets for an environment by matching bindings against scoped secrets.
 *
 * Takes already-filtered bindings (for the target environment). For each binding,
-* finds secrets whose scope matches the binding's scopePattern via picomatch.
-* When multiple scopes provide the same key, longest scope path wins (higher specificity).
-* Scope depth is computed AFTER stripping the backend prefix.
+* finds secrets whose (substituted) scope matches the binding's scopePattern via
+* picomatch. When multiple scopes provide the same key, precedence is the tuple
+* `(host specificity, scope depth)` — a per-host binding (exact host) overrides a
+* fleet-wide one, then longest scope path wins. Scope depth is computed AFTER
+* stripping the backend prefix.
+*
+* When `hostFacts` is supplied (a fan-out child's identity), each binding is
+* gated by its `host_pattern` and its `scope_pattern` is templated per-child
+* (`${agentId}`/`${host}`/`${label:NAME}`). When omitted, only fleet-wide
+* (`'**'`/NULL) non-templated bindings contribute — preserving the workflow-level
+* (no-host) behaviour.
 *
 * @param bindings - Bindings already filtered for the target environment
 * @param allSecrets - All scoped secrets in the org
 * @param decryptFn - Pure decryption function (keeps this module crypto-free)
+* @param hostFacts - Optional fan-out child identity for per-host resolution
 * @returns Flat record of decrypted secret key-value pairs
 */
-function resolveSecretsForEnvironment(bindings, allSecrets, decryptFn) {
-	const candidates = [];
-	for (const binding of bindings) for (const secret of allSecrets) if (matchScopePattern(secret.scope, binding.scopePattern)) {
-		const scopePath = stripScopePrefix(secret.scope);
-		candidates.push({
-			secret,
-			scopeDepth: scopePath.split("/").length
-		});
-	}
+function resolveSecretsForEnvironment(bindings, allSecrets, decryptFn, hostFacts) {
 	const resolved = /* @__PURE__ */ new Map();
-	for (const candidate of candidates) {
-		const existing = resolved.get(candidate.secret.key);
-		if (!existing || candidate.scopeDepth > existing.scopeDepth) resolved.set(candidate.secret.key, candidate);
+	for (const binding of bindings) {
+		const scopePattern = bindingScopeForHost(binding, hostFacts);
+		if (scopePattern === null) continue;
+		const hostSpec = hostSpecificity(binding.hostPattern);
+		for (const secret of allSecrets) {
+			if (!matchScopePattern(secret.scope, scopePattern)) continue;
+			const candidate = {
+				secret,
+				scopeDepth: stripScopePrefix(secret.scope).split("/").length,
+				hostSpec
+			};
+			if (candidateWins(candidate, resolved.get(secret.key))) resolved.set(secret.key, candidate);
+		}
 	}
 	const result = {};
 	for (const [key, { secret }] of resolved) result[key] = decryptFn(secret);

package/dist/environment/scope-template.d.ts

@@ -0,0 +1,18 @@
+import type { HostFacts } from './host-match.js';
+/**
+ * Substitute `${agentId}` / `${host}` / `${label:NAME}` placeholders in a
+ * binding's `scope_pattern` with a fan-out child's identity, so one templated
+ * binding selects each host's own subtree (`prod/hosts/${agentId}/**`).
+ *
+ * Returns the substituted pattern, or `null` when the binding must be **skipped
+ * for this host** because either:
+ * - a referenced variable is unresolved (a missing `${label:NAME}`), or
+ * - a substituted value is unsafe — it contains anything outside
+ *   `[A-Za-z0-9._-]` (a `/` path separator or a glob metacharacter), which
+ *   could let a hostname/label value escape its segment or inject a pattern.
+ *
+ * A multi-valued label resolves to its lexicographic-first value
+ * (deterministic). A pattern with no placeholders is returned unchanged.
+ */
+export declare function substituteScopePattern(pattern: string, facts: HostFacts): string | null;
+//# sourceMappingURL=scope-template.d.ts.map

package/dist/environment/scope-template.js

@@ -0,0 +1,43 @@
+import "../chunk-BTugEXQM.js";
+//#region src/environment/scope-template.ts
+/** A substituted value must be a single literal path segment — no `/` or glob. */
+const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+const PLACEHOLDER = /\$\{(agentId|host|label:[^}]+)\}/g;
+/**
+* Substitute `${agentId}` / `${host}` / `${label:NAME}` placeholders in a
+* binding's `scope_pattern` with a fan-out child's identity, so one templated
+* binding selects each host's own subtree (`prod/hosts/${agentId}/**`).
+*
+* Returns the substituted pattern, or `null` when the binding must be **skipped
+* for this host** because either:
+* - a referenced variable is unresolved (a missing `${label:NAME}`), or
+* - a substituted value is unsafe — it contains anything outside
+*   `[A-Za-z0-9._-]` (a `/` path separator or a glob metacharacter), which
+*   could let a hostname/label value escape its segment or inject a pattern.
+*
+* A multi-valued label resolves to its lexicographic-first value
+* (deterministic). A pattern with no placeholders is returned unchanged.
+*/
+function substituteScopePattern(pattern, facts) {
+	if (!pattern.includes("${")) return pattern;
+	let unresolved = false;
+	const out = pattern.replace(PLACEHOLDER, (_m, token) => {
+		let value;
+		if (token === "agentId") value = facts.agentId;
+		else if (token === "host") value = facts.host;
+		else {
+			const prefix = `${token.slice(6)}:`;
+			value = facts.labels.filter((l) => l.startsWith(prefix)).map((l) => l.slice(prefix.length)).sort()[0];
+		}
+		if (value === void 0 || !SAFE_SEGMENT.test(value)) {
+			unresolved = true;
+			return "";
+		}
+		return value;
+	});
+	return unresolved ? null : out;
+}
+//#endregion
+export { substituteScopePattern };
+
+//# sourceMappingURL=scope-template.js.map

package/dist/environment/types.d.ts

@@ -4,6 +4,7 @@
  * Environments are org-level entities that group secrets, variables,
  * and protection rules for deployment targets (dev, staging, production).
  */
+import { z } from 'zod';
 import type { ApproverClause } from '../approval/types.js';
 /** Environment entity — org-level deployment target with protection rules. */
 export interface Environment {
@@ -48,6 +49,13 @@ export interface EnvironmentBinding {
     orgId: string;
     environmentId: string;
     scopePattern: string;
+    /**
+     * Host selector this binding applies to (exact / glob / regex, matched
+     * against a fan-out child's agentId / hostname / labels). `'**'` matches
+     * every host, preserving fleet-wide behaviour for bindings with no host
+     * scope.
+     */
+    hostPattern: string;
     createdAt: string;
 }
 /** Non-secret key-value config per environment, with optional lock. */
@@ -72,8 +80,13 @@ export interface EnvironmentSourceOverride {
     createdAt: string;
     updatedAt: string;
 }
-/** Trust tier for contributor-based CI execution gating. */
-export type TrustTier = 'trusted' | 'known' | 'unknown';
+/** Trust tier for contributor-based CI execution gating (single source of truth). */
+export declare const TrustTierSchema: z.ZodEnum<{
+    unknown: "unknown";
+    known: "known";
+    trusted: "trusted";
+}>;
+export type TrustTier = z.infer<typeof TrustTierSchema>;
 /** Held run record for protection gate enforcement. */
 export interface HeldRun {
     id: string;

package/dist/environment/types.js

@@ -1,2 +1,19 @@
 import "../chunk-BTugEXQM.js";
-export {};
+import { z } from "zod";
+//#region src/environment/types.ts
+/**
+* Environment types for KiCI's deployment environment model.
+*
+* Environments are org-level entities that group secrets, variables,
+* and protection rules for deployment targets (dev, staging, production).
+*/
+/** Trust tier for contributor-based CI execution gating (single source of truth). */
+const TrustTierSchema = z.enum([
+	"trusted",
+	"known",
+	"unknown"
+]);
+//#endregion
+export { TrustTierSchema };
+
+//# sourceMappingURL=types.js.map