@kici-dev/engine 0.1.22 → 0.1.23

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

@@ -152,6 +152,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" },

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.
  */
@@ -76,6 +76,7 @@ export declare const activityRowSchema: z.ZodObject<{
         platform_proxy: "platform_proxy";
         admin_http: "admin_http";
         admin_cli: "admin_cli";
+        agent: "agent";
     }>>>;
 }, z.core.$strip>;
 export type ActivityRow = z.infer<typeof activityRowSchema>;
@@ -108,6 +109,7 @@ export declare const activityFilterSchema: z.ZodObject<{
         platform_proxy: "platform_proxy";
         admin_http: "admin_http";
         admin_cli: "admin_cli";
+        agent: "agent";
     }>>;
     targetType: z.ZodOptional<z.ZodString>;
     targetId: z.ZodOptional<z.ZodString>;

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

@@ -65,6 +65,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,
@@ -307,6 +309,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,4 @@
 export type { Environment, EnvironmentBinding, EnvironmentVariable, EnvironmentSourceOverride, ScopedSecret, HeldRun, ProtectionGateResult, TrustTier, } from './types.js';
 export { resolveSecretsForEnvironment, matchScopePattern, stripScopePrefix, } from './scope-resolver.js';
+export type { HostFacts } from './host-match.js';
 //# sourceMappingURL=index.d.ts.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

@@ -48,6 +48,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. */

package/dist/fanout/materialize.d.ts

@@ -53,6 +53,13 @@ export interface ResolvedHostAgent {
     arch?: string;
     /** Which orchestrator owns the live WS (null = not currently connected). */
     connectedInstanceId?: string | null;
+    /**
+     * True when this host is a declared-but-un-agented `includeUninitialized`
+     * target: it has no live agent, so the dispatcher first brings up a temporary
+     * init-runner over SSH before the child's pinned steps can land. False / absent
+     * for a live host (runs on its own agent directly).
+     */
+    needsBringup?: boolean;
 }
 /**
  * One dispatchable unit produced from a lock job. `variantKind` is `matrix` for
@@ -83,6 +90,20 @@ export interface MaterializedJob {
     agent?: ResolvedHostAgent;
     /** Which orchestrator owns the pinned agent's live WS (null = not connected). */
     connectedInstanceId?: string | null;
+    /**
+     * True for a declared-but-un-agented `includeUninitialized` host child: the
+     * dispatcher brings up a temporary init-runner over SSH before its pinned
+     * steps land. Mirrors `agent.needsBringup`.
+     */
+    needsBringup?: boolean;
+    /**
+     * 0-based position of this child in the deterministically-ordered fan-out
+     * (host: by `agentId`; matrix: by variant label). Exposed to the agent as
+     * `ctx.fanout.index`. Absent on a non-fan-out (single-child) job.
+     */
+    fanoutIndex?: number;
+    /** Number of children in this fan-out. Exposed as `ctx.fanout.total`. */
+    fanoutTotal?: number;
 }
 export interface FanoutResult {
     jobs: MaterializedJob[];
@@ -101,6 +122,17 @@ export declare function matrixEnvelopeFields(mat: MaterializedJob): {
     name: string;
     baseJobName: string;
     matrixValues?: MatrixValues;
+    fanoutIndex?: number;
+    fanoutTotal?: number;
+};
+/**
+ * The fan-out position envelope fields (`fanoutIndex`/`fanoutTotal`) of a
+ * materialized child, shared by the matrix + host envelope builders. Both are
+ * present together or absent together (a non-fan-out child has neither).
+ */
+export declare function fanoutEnvelopeFields(mat: MaterializedJob): {
+    fanoutIndex?: number;
+    fanoutTotal?: number;
 };
 /**
  * Build materialized children from a resolved dynamic-matrix combination list
@@ -122,6 +154,8 @@ export declare function hostEnvelopeFields(mat: MaterializedJob): {
     host?: string;
     agent?: ResolvedHostAgent;
     connectedInstanceId?: string | null;
+    fanoutIndex?: number;
+    fanoutTotal?: number;
 };
 /**
  * Build materialized host children from a resolved target-host list (produced by

package/dist/fanout/materialize.js

@@ -48,6 +48,30 @@ var FanoutError = class FanoutError extends Error {
 	}
 };
 /**
+* Stamp a deterministic `fanoutIndex`/`fanoutTotal` onto each child of a
+* multi-child fan-out. `fanoutIndex` is the child's rank in the order defined by
+* `keyOf` (host: `agentId`; matrix: variant label), independent of emission
+* order — the orchestrator's wave dispatch keys on `fanoutIndex`, so emission
+* order need not be touched (this preserves the local-executor matrix naming
+* order). A single child gets no position (non-fan-out job; `ctx.fanout` stays
+* undefined). Mutates and returns the same array.
+*/
+function assignFanoutPositions(children, keyOf) {
+	if (children.length <= 1) return children;
+	const total = children.length;
+	const rank = /* @__PURE__ */ new Map();
+	[...children].sort((a, b) => keyOf(a).localeCompare(keyOf(b))).forEach((child, index) => rank.set(child, index));
+	for (const child of children) {
+		child.fanoutIndex = rank.get(child);
+		child.fanoutTotal = total;
+	}
+	return children;
+}
+/** Variant label of a child = the text inside the trailing `(...)` of its expanded name. */
+function variantLabelOf(child) {
+	return child.expandedName.slice(child.baseName.length + 2, -1);
+}
+/**
 * The job-config envelope fields that identify a materialized child: the
 * expanded `name`, the `baseJobName` (what the agent exposes as `ctx.job.name`),
 * and `matrixValues` (exposed as `ctx.matrix`). Every dispatch site spreads
@@ -59,10 +83,22 @@ function matrixEnvelopeFields(mat) {
 	return {
 		name: mat.expandedName,
 		baseJobName: mat.baseName,
-		...mat.variantValues && { matrixValues: mat.variantValues }
+		...mat.variantValues && { matrixValues: mat.variantValues },
+		...fanoutEnvelopeFields(mat)
 	};
 }
 /**
+* The fan-out position envelope fields (`fanoutIndex`/`fanoutTotal`) of a
+* materialized child, shared by the matrix + host envelope builders. Both are
+* present together or absent together (a non-fan-out child has neither).
+*/
+function fanoutEnvelopeFields(mat) {
+	return mat.fanoutTotal !== void 0 ? {
+		fanoutIndex: mat.fanoutIndex,
+		fanoutTotal: mat.fanoutTotal
+	} : {};
+}
+/**
 * Build materialized children from a resolved dynamic-matrix combination list
 * (produced by the agent eval flow). Mirrors the static-matrix branch of
 * {@link materializeFanout} but takes the already-resolved combinations and
@@ -72,21 +108,17 @@ function materializeResolvedMatrix(lockJob, combos) {
 	if (combos.length === 0) throw new FanoutError(lockJob.name, `dynamic matrix for job '${lockJob.name}' resolved to zero combinations`);
 	if (combos.length > 256) throw new FanoutError(lockJob.name, `dynamic matrix for job '${lockJob.name}' resolved to ${combos.length} combinations (max 256)`);
 	const jobs = [];
-	const names = [];
-	for (const variantValues of combos) {
-		const expandedName = formatExpandedJobName(lockJob.name, variantValues);
-		names.push(expandedName);
-		jobs.push({
-			lockJob,
-			baseName: lockJob.name,
-			expandedName,
-			variantKind: "matrix",
-			variantValues
-		});
-	}
+	for (const variantValues of combos) jobs.push({
+		lockJob,
+		baseName: lockJob.name,
+		expandedName: formatExpandedJobName(lockJob.name, variantValues),
+		variantKind: "matrix",
+		variantValues
+	});
+	assignFanoutPositions(jobs, variantLabelOf);
 	return {
 		jobs,
-		expansionMap: new Map([[lockJob.name, names]])
+		expansionMap: new Map([[lockJob.name, jobs.map((j) => j.expandedName)]])
 	};
 }
 /**
@@ -102,7 +134,8 @@ function hostEnvelopeFields(mat) {
 		...mat.pinnedAgentId && { pinnedAgentId: mat.pinnedAgentId },
 		...mat.host && { host: mat.host },
 		...mat.agent && { agent: mat.agent },
-		...mat.connectedInstanceId !== void 0 && { connectedInstanceId: mat.connectedInstanceId }
+		...mat.connectedInstanceId !== void 0 && { connectedInstanceId: mat.connectedInstanceId },
+		...fanoutEnvelopeFields(mat)
 	};
 }
 /**
@@ -116,24 +149,21 @@ function materializeResolvedHosts(lockJob, agents, maxHosts) {
 	if (agents.length === 0) throw new FanoutError(lockJob.name, `runsOnAll for job '${lockJob.name}' matched zero matching hosts`);
 	if (agents.length > maxHosts) throw new FanoutError(lockJob.name, `runsOnAll for job '${lockJob.name}' matched ${agents.length} hosts (max ${maxHosts})`);
 	const jobs = [];
-	const names = [];
-	for (const agent of agents) {
-		const expandedName = `${lockJob.name} (${agent.host})`;
-		names.push(expandedName);
-		jobs.push({
-			lockJob,
-			baseName: lockJob.name,
-			expandedName,
-			variantKind: "host",
-			pinnedAgentId: agent.agentId,
-			host: agent.host,
-			agent,
-			connectedInstanceId: agent.connectedInstanceId ?? null
-		});
-	}
+	for (const agent of agents) jobs.push({
+		lockJob,
+		baseName: lockJob.name,
+		expandedName: `${lockJob.name} (${agent.host})`,
+		variantKind: "host",
+		pinnedAgentId: agent.agentId,
+		host: agent.host,
+		agent,
+		connectedInstanceId: agent.connectedInstanceId ?? null,
+		...agent.needsBringup && { needsBringup: true }
+	});
+	assignFanoutPositions(jobs, (child) => child.pinnedAgentId ?? "");
 	return {
 		jobs,
-		expansionMap: new Map([[lockJob.name, names]])
+		expansionMap: new Map([[lockJob.name, jobs.map((j) => j.expandedName)]])
 	};
 }
 /**
@@ -170,19 +200,16 @@ function materializeFanout(staticJobs) {
 		const combos = applyIncludeExclude(expandMatrix(values), lockJob.include, lockJob.exclude);
 		if (combos.length === 0) throw new FanoutError(lockJob.name, `matrix for job '${lockJob.name}' expands to zero combinations`);
 		if (combos.length > 256) throw new FanoutError(lockJob.name, `matrix for job '${lockJob.name}' expands to ${combos.length} combinations (max 256)`);
-		const names = [];
-		for (const variantValues of combos) {
-			const expandedName = formatExpandedJobName(lockJob.name, variantValues);
-			names.push(expandedName);
-			jobs.push({
-				lockJob,
-				baseName: lockJob.name,
-				expandedName,
-				variantKind: "matrix",
-				variantValues
-			});
-		}
-		expansionMap.set(lockJob.name, names);
+		const children = combos.map((variantValues) => ({
+			lockJob,
+			baseName: lockJob.name,
+			expandedName: formatExpandedJobName(lockJob.name, variantValues),
+			variantKind: "matrix",
+			variantValues
+		}));
+		assignFanoutPositions(children, variantLabelOf);
+		jobs.push(...children);
+		expansionMap.set(lockJob.name, children.map((j) => j.expandedName));
 	}
 	return {
 		jobs,
@@ -190,6 +217,6 @@ function materializeFanout(staticJobs) {
 	};
 }
 //#endregion
-export { FanoutCause, FanoutError, MAX_FANOUT_JOBS, VariantKind, hostEnvelopeFields, materializeFanout, materializeResolvedHosts, materializeResolvedMatrix, matrixEnvelopeFields };
+export { FanoutCause, FanoutError, MAX_FANOUT_JOBS, VariantKind, fanoutEnvelopeFields, hostEnvelopeFields, materializeFanout, materializeResolvedHosts, materializeResolvedMatrix, matrixEnvelopeFields };
 
 //# sourceMappingURL=materialize.js.map

package/dist/index.d.ts

@@ -36,6 +36,7 @@ export * from './trigger/types.js';
 export * from './trigger/trigger-event-type.js';
 export * from './trigger/decision-trace.js';
 export * from './trigger/matcher.js';
+export * from './inputs/index.js';
 export * from './state-machine/index.js';
 export * from './provider/index.js';
 export { githubWebhookPath } from './webhook/webhook-url-format.js';
@@ -46,7 +47,7 @@ export type { RateLimiterConfig, RateLimitResult } from './ws/rate-limiter.js';
 export * from './env/environment-allowlist.js';
 export * from './secrets/index.js';
 export * from './environment/index.js';
-export { deriveOsArchLabels, hostLabel, parseHostLabel, HOST_LABEL_PREFIX, agentTypeLabel, scalerLabel, mergeAutoLabels, normalizeRunsOn, KNOWN_ROLES, resolveRoleLabels, validateNoReservedLabels, scalerAgentLabels, isSelfReportedLabel, SELF_REPORTED_LABEL_PREFIXES, } from './labels.js';
+export { deriveOsArchLabels, hostLabel, parseHostLabel, HOST_LABEL_PREFIX, agentTypeLabel, scalerLabel, mergeAutoLabels, normalizeRunsOn, KNOWN_ROLES, resolveRoleLabels, validateNoReservedLabels, scalerAgentLabels, isSelfReportedLabel, SELF_REPORTED_LABEL_PREFIXES, CAPABILITY_LABEL_PREFIX, capabilityLabel, SSH_TRANSPORT_CAPABILITY, INIT_LABEL, PRIVILEGED_ROOT_LABEL, } from './labels.js';
 export type { NormalizedRunsOn } from './labels.js';
 export type { AgentRole } from './labels.js';
 export { LabelMatcher, matcherMatches, matcherSatisfiedBy, partitionMatchers, compileRegexMatcher, HostTargetValue, HostTargetSelector, hostSatisfiesTarget, } from './labels-match.js';