@kici-dev/engine 0.1.21 → 0.1.23

package/dist/approval/types.d.ts

@@ -2,7 +2,7 @@
  * Shared approval requirement + clause types.
  *
  * One normalized `ApprovalRequirement` is produced by both approval triggers —
- * a mandatory environment policy and an explicit SDK `requireApproval` — and is
+ * a mandatory environment policy and an explicit SDK `approval` config — and is
  * consumed identically by the orchestrator gate, the resolver, the held-run
  * store, and the agent step round-trip. Pure Zod (no node built-ins), so this
  * module is safe in the browser-facing engine barrel.

package/dist/approval/types.js

@@ -5,7 +5,7 @@ import { z } from "zod";
 * Shared approval requirement + clause types.
 *
 * One normalized `ApprovalRequirement` is produced by both approval triggers —
-* a mandatory environment policy and an explicit SDK `requireApproval` — and is
+* a mandatory environment policy and an explicit SDK `approval` config — and is
 * consumed identically by the orchestrator gate, the resolver, the held-run
 * store, and the agent step round-trip. Pure Zod (no node built-ins), so this
 * module is safe in the browser-facing engine barrel.

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

@@ -111,6 +111,10 @@ const POLICY_BY_ACTION = {
 		kind: "rate_limit",
 		perMinutePerActor: 1
 	},
+	"fleet.read": {
+		kind: "rate_limit",
+		perMinutePerActor: 1
+	},
 	"run.payload.read": { kind: "always" },
 	"run.cancel": { kind: "always" },
 	"run.rerun": { kind: "always" },
@@ -137,6 +141,7 @@ const POLICY_BY_ACTION = {
 	"secret_scope.rename": { kind: "always" },
 	"secret_scope.delete": { kind: "always" },
 	"held_run.approve": { kind: "always" },
+	"held_run.auto_approve": { kind: "always" },
 	"held_run.reject": { kind: "always" },
 	"held_run.request": { kind: "always" },
 	"held_run.expire": { kind: "always" },
@@ -145,6 +150,10 @@ const POLICY_BY_ACTION = {
 	"backend.sync": { kind: "always" },
 	"backend.sync.one": { kind: "always" },
 	"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

@@ -32,6 +32,7 @@ const ACCESS_LOG_WARM_DAYS = {
 	"diagnostics.read": 30,
 	"scaler.capacity.read": 30,
 	"scaler.agents.read": 30,
+	"fleet.read": 30,
 	"event_log.detail.read": 180,
 	"event_log.payload.read": 180,
 	"run.payload.read": 180,
@@ -53,6 +54,7 @@ const ACCESS_LOG_WARM_DAYS = {
 	"source_override.delete": 180,
 	"env_binding.set": 180,
 	"held_run.approve": 180,
+	"held_run.auto_approve": 180,
 	"held_run.reject": 180,
 	"held_run.request": 180,
 	"held_run.expire": 180,
@@ -61,6 +63,10 @@ const ACCESS_LOG_WARM_DAYS = {
 	"backend.sync": 180,
 	"backend.sync.one": 180,
 	"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,
@@ -270,6 +276,7 @@ const ACCESS_LOG_COLD_DAYS = {
 	"diagnostics.read": 30,
 	"scaler.capacity.read": 30,
 	"scaler.agents.read": 30,
+	"fleet.read": 30,
 	"event_log.detail.read": 730,
 	"event_log.payload.read": 730,
 	"run.payload.read": 730,
@@ -291,6 +298,7 @@ const ACCESS_LOG_COLD_DAYS = {
 	"source_override.delete": 730,
 	"env_binding.set": 730,
 	"held_run.approve": 730,
+	"held_run.auto_approve": 730,
 	"held_run.reject": 730,
 	"held_run.request": 730,
 	"held_run.expire": 730,
@@ -299,6 +307,10 @@ const ACCESS_LOG_COLD_DAYS = {
 	"backend.sync": 730,
 	"backend.sync.one": 730,
 	"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

@@ -12,14 +12,31 @@ export declare enum VariantKind {
     host = "host"
 }
 /**
- * Thrown when a job's matrix cannot be materialized into dispatchable children:
- * zero combinations after exclude, or more combinations than {@link MAX_FANOUT_JOBS}.
- * Callers map this onto the `matrix_expansion` init-failure category.
+ * Why a fan-out produced no dispatchable children. Drives whether the zeroed
+ * job's synthetic terminal row is recorded as a failure or a skip:
+ *
+ * - `error` — a genuine failure: invalid matrix (zero combinations / over the
+ *   cap), an unavailable roster, or `onUnreachable: 'fail'` with an absent host.
+ *   The synthetic job is `failed`.
+ * - `narrowed-empty` — the fan-out intentionally resolved to zero usable hosts
+ *   (e.g. `onUnreachable: 'skip'` skipped every unreachable host). The synthetic
+ *   job is `skipped`.
+ */
+export declare enum FanoutCause {
+    error = "error",
+    narrowedEmpty = "narrowed-empty"
+}
+/**
+ * Thrown when a job's fan-out cannot be materialized into dispatchable children:
+ * an invalid matrix, an unavailable / zeroed host roster. The `cause` discriminates
+ * a genuine failure from an intentional narrow-to-empty so the caller can record
+ * the zeroed job's synthetic row as `failed` or `skipped` accordingly.
  */
 export declare class FanoutError extends Error {
     readonly jobName: string;
+    readonly cause: FanoutCause;
     readonly name = "FanoutError";
-    constructor(jobName: string, message: string);
+    constructor(jobName: string, message: string, cause?: FanoutCause);
 }
 /**
  * A roster host resolved as a target of a `runsOnAll` fan-out. Carries the
@@ -36,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
@@ -66,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[];
@@ -84,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
@@ -105,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