@kici-dev/orchestrator 0.1.21 → 0.1.23

package/dist/pipeline/dispatch-matched-workflow.d.ts

@@ -13,11 +13,13 @@
  * exported function is a narrative orchestrator that threads the typed
  * results through the pipeline.
  */
-import { CacheRefScope } from '@kici-dev/engine';
-import type { LabelMatcher, LockWorkflow, LockJob, SimulatedEvent, WorkflowDecision, MaterializedJob } from '@kici-dev/engine';
+import { ExecutionJobStatus, InitFailureCategory, CacheRefScope } from '@kici-dev/engine';
+import type { LabelMatcher, LockWorkflow, LockJob, HostTargetSelector, SimulatedEvent, WorkflowDecision, MaterializedJob, ResolvedHostAgent, HostFacts } from '@kici-dev/engine';
 import { type HostRosterStore } from '../agent/host-roster.js';
 import type { WebhookInfo } from '../webhook/handler.js';
 import type { ProviderBundle } from '../provider-registry.js';
+import type { Dispatcher } from '../agent/dispatcher.js';
+import type { QueuedJobInput } from '../queue/job-queue.js';
 import type { TrustResolution } from '../security/trust-resolver.js';
 import { type ProcessingDeps } from './processor.js';
 /**
@@ -41,7 +43,15 @@ export declare function deriveCacheRefScope(trust: TrustResolution | undefined):
 export interface WorkflowDispatchContext {
     info: WebhookInfo;
     deps: ProcessingDeps;
-    bundle: ProviderBundle;
+    /**
+     * Provider bundle for the matched source. Undefined for local-repo test runs
+     * (`kici run` against an inline lock file with no remote provider): in that
+     * mode there is no clone-url builder / check-status poster / clone-token
+     * provider, and `repoUrl` falls back to `''` (the agent treats a missing url
+     * as a local/`fullRepo` clone). The webhook adapter always passes a defined
+     * bundle, so its dispatch behavior is unchanged.
+     */
+    bundle?: ProviderBundle;
     payload: unknown;
     repoIdentifier: string;
     credentials: Record<string, unknown>;
@@ -88,10 +98,42 @@ export interface WorkflowDispatchContext {
      * correct clone + logging.
      */
     extraJobConfig?: Record<string, unknown>;
+    /**
+     * Test-run provenance. Present only for `kici run` / test-trigger dispatches.
+     * When set, `recordRunStart` stamps `is_test_run = true` and
+     * `fixture_id = testRun.fixtureId` on the `execution_runs` row. Undefined for
+     * webhook runs (the stamp block is skipped).
+     */
+    testRun?: {
+        fixtureId: string;
+    };
+    /**
+     * Run-wide flat secrets layered onto EVERY dispatched job's `jobConfig.secrets`
+     * (env-declaring or not). Used by the test path to deliver `kici run --secret`
+     * / `--env` CLI flat secrets, which must reach a job regardless of whether it
+     * declares an `environment:`. Merged UNDER the per-job env-resolved secrets so
+     * the CLI value wins on a key collision (matching the prior B1-env -> A-CLI
+     * precedence). Undefined for webhook runs.
+     */
+    runWideFlatSecrets?: Record<string, string>;
+    /**
+     * Runtime host narrowing from `kici run --target` (Ansible `--limit`). Applied
+     * as a post-filter over each runsOnAll job's matched roster: effective hosts =
+     * runsOnAll ∩ target. Narrow-only. Undefined for webhook runs (no narrowing).
+     */
+    target?: HostTargetSelector;
+    /**
+     * Resolved (coerced + defaulted + validated) workflow-dispatch inputs from
+     * `kici run --input`. Carried onto every dispatched job's request so the agent
+     * exposes them as `ctx.dispatchInputs`. Undefined for webhook runs.
+     */
+    dispatchInputs?: Record<string, unknown>;
 }
 export interface DispatchMatchedWorkflowResult {
     /** Number of jobs successfully dispatched (non-rejected). */
     dispatchedJobCount: number;
+    /** Execution job ids of every dispatched/tracked job (root, gated, synthetic). */
+    dispatchedJobIds: string[];
     /** True when the workflow install gate paused the dispatch (held run). */
     held?: boolean;
 }
@@ -110,6 +152,77 @@ export interface DispatchMatchedWorkflowOptions {
      */
     reuseRunId?: string;
 }
+type DispatchFn = (input: QueuedJobInput) => ReturnType<Dispatcher['dispatch']>;
+interface DispatchSetup {
+    /** Wrapped dispatcher that injects ctx.extraJobConfig into every dispatch. */
+    dispatcher: {
+        dispatch: DispatchFn;
+    };
+    /** WebhookInfo overlaid with effective routing key + provider. */
+    info: WebhookInfo;
+    /** Composite delivery id on cross-source, otherwise info.deliveryId. */
+    effectiveDeliveryId: string;
+    workflowConcurrency: {
+        cancelInProgress?: boolean;
+        max?: number;
+    } | undefined;
+    workflowTimeoutMs: number | undefined;
+    /**
+     * Run mode for idempotent steps (`apply` | `check` | `check-fail-on-drift`),
+     * carried on `ctx.extraJobConfig` by the test-trigger / `kici run --check`
+     * path. Persisted onto the `execution_runs` row so `computeRunStatus` can
+     * fail a `check-fail-on-drift` run that detected drift. Undefined for the
+     * default apply-mode webhook path.
+     */
+    checkMode: string | undefined;
+}
+interface RejectedJob {
+    jobId: string;
+    jobName: string;
+    reason: string;
+    /** Explicit init-failure category override; inferred from reason when absent. */
+    category?: InitFailureCategory;
+    /**
+     * Terminal status to record for this job. Defaults to `failed`. A zeroed
+     * `runsOnAll` that intentionally narrowed to no hosts is recorded as `skipped`
+     * (no init-failure) so its downstreams' `when` sets govern propagation.
+     */
+    terminalStatus?: ExecutionJobStatus;
+}
+/**
+ * Build the QueuedJobInput for a synthetic `__bringup__` job: the orchestrator
+ * dispatches one per declared-but-un-agented `includeUninitialized` child to an
+ * agent holding `kici:capability:ssh-transport`, which runs the agent-side
+ * `ensureInitRunner(targetAgentId)` over SSH. The init-runner then connects
+ * under `targetAgentId`, and the child's pinned-hold (already queued with that
+ * pin) drains its bootstrap steps onto it. The bring-up job clones nothing and
+ * runs no sandbox (`bringupOnly`).
+ */
+export declare function buildBringupJobInput(args: {
+    ctx: WorkflowDispatchContext;
+    setup: DispatchSetup;
+    targetAgentId: string;
+}): QueuedJobInput;
+/**
+ * Phase B orchestrator: probe caches, dispatch the build job (if needed),
+ * and surface enough state for downstream phases to skip / continue
+ * appropriately.
+ */
+/**
+ * Materialize each static job's matrix into dispatchable children. A job whose
+ * matrix is invalid (zero combinations / over the cap) is dropped from the
+ * dispatch list and recorded as a `matrix_expansion` matrix failure so the run's
+ * other jobs still proceed. Dynamic-matrix jobs pass through with a
+ * `pendingDynamicMatrix` marker for the eval flow.
+ */
+/**
+ * Resolve a `runsOnAll` lock job against the declared host roster and partition
+ * the matched hosts into the target set per the `onUnreachable` policy (R2):
+ * `ready` hosts always run; unreachable durable (`static`) hosts hold / fail /
+ * skip; stale ephemeral hosts are always skipped. Throws {@link FanoutError}
+ * when the run can't proceed (fail policy with an absent host, or zero targets).
+ */
+export declare function resolveHostFanoutTargets(lockJob: LockJob, deps: ProcessingDeps, target?: HostTargetSelector): Promise<ResolvedHostAgent[]>;
 /** Exact labels + regex patterns partitioned from a lock job's selectors. */
 interface JobRoutingSelectors {
     runsOnLabels: string[];
@@ -160,8 +273,9 @@ export interface WavePlan {
  * Compute the rolling-wave plan for a materialized job set.
  *
  * For each base job declaring `maxParallel` whose fan-out produced more than one
- * child, children are ordered deterministically by `variant_label` (the matrix
- * suffix / hostname, via `expandedName`) and every child at index `>=
+ * child, children are ordered deterministically by `fanoutIndex` (the
+ * agentId / variant-label rank assigned at materialization; falling back to
+ * `expandedName` for children with no index) and every child at index `>=
  * maxParallel` is held (`wave_gated=true`). The first `maxParallel` dispatch
  * immediately; held children release one-per-terminal via the wave-scheduler.
  * Every child of a bounded-wave base — held or not — gets a `policy` entry so
@@ -169,6 +283,19 @@ export interface WavePlan {
  * job (single child) or one without `maxParallel` contributes nothing.
  */
 export declare function computeWavePlan(materializedJobs: readonly MaterializedJob[]): WavePlan;
+export declare function materializeStaticJobsSafe(staticJobs: readonly LockJob[], deps: ProcessingDeps, target?: HostTargetSelector): Promise<{
+    materializedJobs: MaterializedJob[];
+    expansionMap: Map<string, readonly string[]>;
+    matrixFailures: RejectedJob[];
+}>;
+/**
+ * Build the per-host secret-resolution context for a materialized child. A
+ * `runsOnAll` host child carries its identity on `mat.agent` (preferred) or
+ * `mat.pinnedAgentId`/`mat.host`; a non-host child (matrix/static) has none, so
+ * resolution stays fleet-wide (`'**'`-only). Returns `undefined` when there are
+ * no host facts to scope by.
+ */
+export declare function hostCtxFromMat(mat: MaterializedJob): HostFacts | undefined;
 export interface GeneratedJobConfig {
     /**
      * The generated lock job with its `name` and `needs` rewritten to expanded

package/dist/pipeline/install-secrets-resolver.d.ts

@@ -31,7 +31,7 @@
  */
 import type { ApproverClause, LockRegistry } from '@kici-dev/engine';
 import type { TrustResolution } from '../security/trust-resolver.js';
-import type { SecretResolver } from '../secrets/secret-resolver.js';
+import type { SecretResolverApi } from '../secrets/secret-resolver.js';
 import type { EnvironmentStore } from '../environments/environment-store.js';
 import { type JobDispatchContext } from '../environments/protection/pipeline.js';
 /** Registry spec carried on the dispatch message (token already resolved). */
@@ -48,7 +48,7 @@ export interface ResolveInstallSecretsArgs {
     resolvedOrgId: string;
     trustResolution: TrustResolution | undefined;
     environmentStore: EnvironmentStore | undefined;
-    secretResolver: SecretResolver | undefined;
+    secretResolver: SecretResolverApi | undefined;
     protectionContext: JobDispatchContext;
     /**
      * Resume path: skip the protection-rule gate (already satisfied) and resolve

package/dist/pipeline/needs-scheduler.d.ts

@@ -1,24 +1,29 @@
 /**
- * DB-backed needs-aware dispatch scheduler ( through).
+ * DB-backed needs-aware dispatch scheduler.
  *
- * This module is the core of 's behavioral change: it replaces the
- * "concurrent dispatch" model with event-driven scheduling that gates ALL
- * needs edges (static-to-static, static-to-dyn-group, dyn-to-static, dyn-to-dyn).
+ * Gates ALL needs edges (static-to-static, static-to-dyn-group, dyn-to-static,
+ * dyn-to-dyn) with event-driven scheduling instead of concurrent dispatch.
  *
  * The scheduler is pure DB — no in-memory state. Every scheduling decision is
  * a fresh DB query against execution_jobs + execution_job_needs. This means
  * zero recovery code on orchestrator restart.
  *
+ * Each edge carries a `run_on` status-set (the upstream terminal statuses that
+ * satisfy the edge). A downstream edge is dispatch-satisfied when the upstream's
+ * terminal status is a member of the edge's run_on set; otherwise the downstream
+ * is skipped. A downstream dispatches only when every edge is satisfied.
+ *
  * Entry points:
  * - insertEdgesForRun: called at run start for static-to-static edges
  * - resolveGroupEdges: called on dynamic-eval completion
  * - evaluateDownstreams: called from onJobStatus(terminal)
  * - recomputeNeedsSatisfied: batch recompute after group resolution
- * - checkSchedulerInvariant: Layer 3 defensive check
+ * - checkSchedulerInvariant: defensive stuck-job check
  * - getFailurePropagationTargets: cascade for transitive skip
  */
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
+import { ExecutionJobStatus } from '@kici-dev/engine';
 import type { MaterializedJob } from '@kici-dev/engine';
 /** Result of evaluating downstream jobs after an upstream completes. */
 export interface SchedulerResult {
@@ -48,21 +53,22 @@ export declare function insertEdgesForRun(db: Kysely<Database>, runId: string, j
  * edge row. Empty groups (0 members) trigger immediate needs_satisfied=true
  * for dependents.
  *
- * CRITICAL: dependentStaticJobs carries per-job ifFailed policy from the
+ * CRITICAL: dependentStaticJobs carries the per-job run_on status-set from the
  * NeedsGroupEntry in the lock file. Without this, all group edges would
- * silently default to 'skip'.
+ * silently default to success-only.
  */
 export declare function resolveGroupEdges(db: Kysely<Database>, runId: string, groupName: string, memberJobNames: string[], dependentStaticJobs: Array<{
     jobName: string;
-    ifFailed: 'skip' | 'run';
+    runOn: ExecutionJobStatus[];
 }>): Promise<void>;
 /**
  * Evaluate downstream jobs after an upstream reaches terminal state.
  *
  * This is the core scheduler hook. For each downstream of the completed job:
- * 1. If upstream failed and edge has if_failed='skip', mark downstream as 'skip'
- * 2. Otherwise, check if ALL upstreams are terminal
- * 3. If all satisfied, mark needs_satisfied=true and return for dispatch
+ * 1. If the completed status is not in this edge's run_on set, mark the
+ *    downstream as 'skip' immediately.
+ * 2. Otherwise, check if ALL upstreams are terminal and satisfied.
+ * 3. If all satisfied, mark needs_satisfied=true and return for dispatch.
  */
 export declare function evaluateDownstreams(db: Kysely<Database>, runId: string, completedJobName: string, completedStatus: string): Promise<SchedulerResult[]>;
 /**
@@ -80,8 +86,11 @@ export declare function recomputeNeedsSatisfied(db: Kysely<Database>, runId: str
  */
 export declare function checkSchedulerInvariant(db: Kysely<Database>, runId: string): Promise<string[]>;
 /**
- * cascade: find all transitive downstreams that should be skipped
- * due to failure propagation. Only follows edges where if_failed='skip'.
+ * Failure-propagation cascade: find all transitive downstreams that should be
+ * skipped because a terminal upstream's status is not in their edge's run_on
+ * set. At each hop, the propagating job's actual terminal status decides which
+ * downstream edges propagate (status not in run_on → the downstream skips and
+ * propagates further).
  */
 export declare function getFailurePropagationTargets(db: Kysely<Database>, runId: string, failedJobName: string): Promise<string[]>;
 //# sourceMappingURL=needs-scheduler.d.ts.map

package/dist/pipeline/processor.d.ts

@@ -33,7 +33,7 @@ import type { HostRosterStore } from '../agent/host-roster.js';
 import type { RunCoordinator } from '../cluster/coordinator.js';
 import type { TeamMembershipLookup } from '../approvals/team-membership-lookup.js';
 import type { LogStorage } from '../reporting/log-storage.js';
-import type { SecretResolver } from '../secrets/secret-resolver.js';
+import type { SecretResolverApi } from '../secrets/secret-resolver.js';
 import type { ContributorCache } from '../security/contributor-cache.js';
 import type { AccessLogWriter } from '../audit/access-log.js';
 import type { LockFile as FullLockFile, LockWorkflow, SimulatedEvent, WebhookNormalizer } from '@kici-dev/engine';
@@ -281,7 +281,7 @@ export interface ProcessingDeps {
     /** Run coordinator for multi-orchestrator job routing. Optional -- if not set, all jobs dispatch locally (single-orchestrator mode). */
     coordinator?: RunCoordinator;
     /** Secret resolver for dispatch-time secret resolution. Optional -- if not set, secrets are not resolved. */
-    secretResolver?: SecretResolver;
+    secretResolver?: SecretResolverApi;
     /** Optional callback when source locations are extracted from a lock file workflow. */
     onSourceLocationsExtracted?: (workflowName: string, jobName: string, sourceLocations: Array<{
         file: string;

package/dist/pipeline/test-pipeline.d.ts

@@ -1,36 +1,28 @@
 /**
- * Test pipeline processor for CLI-initiated test runs.
+ * Test-trigger adapter for CLI-initiated runs (`kici run`).
  *
- * Reuses the existing webhook processing pipeline steps (lock file fetch,
- * trigger matching, job dispatch) but injects a synthetic event instead
- * of processing a real webhook. This avoids the anti-pattern of calling
- * processWebhook() directly (which expects WebhookInfo from a real webhook).
+ * Resolves the lock file, matched decisions, and fixture-specific concerns
+ * (inline-vs-provider lock, decision selection, fixture-payload storage, the
+ * `allow_local_execution` environment gate, CLI-secret overlay, in-memory
+ * test-run marking), then dispatches each matched workflow through the SAME
+ * shared core as webhooks (`dispatchMatchedWorkflow`). The test path is a thin
+ * adapter — needs-DAG scheduling, `expansionMap` fan-out edges, `runsOnAll`
+ * host fan-out, and deferred init/dynamic dispatch all come from the core.
  *
- * Key differences from processWebhook():
- * - Skips dedup check (test runs are always unique)
- * - Skips webhook normalization (event is already in SimulatedEvent shape)
- * - Skips repo extraction from payload (routing key is provided directly)
- * - deliveryId has `test:` prefix for identification
- * - Execution runs are marked with is_test_run=true and fixture_id
- * - Supports direct workflow execution (bypass trigger matching)
+ * Differences from a webhook run:
+ * - the synthetic event is injected directly (no provider normalization/dedup);
+ * - the lock file may be inline (local repos have no remote provider, so
+ *   `bundle` is undefined);
+ * - `deliveryId` carries a `test:` prefix;
+ * - the run is stamped `is_test_run = true` + `fixture_id` (via the core's
+ *   `testRun` meta) and marked in-memory for live-log broadcast to the CLI;
+ * - CLI-uploaded local secrets win over orchestrator env secrets (the
+ *   decorating secret resolver), and the fixture's `secrets` context mapping
+ *   resolves into namespaced secrets;
+ * - direct workflow execution (bypass trigger matching) is supported.
  */
-import type { LockFileCache } from '../lockfile-cache.js';
-import type { Dispatcher } from '../agent/dispatcher.js';
-import type { CheckRunReporter } from '../reporting/check-run-reporter.js';
-import type { ExecutionTracker } from '../reporting/execution-tracker.js';
-import type { AgentRegistry } from '../agent/registry.js';
-import type { ProviderRegistry } from '../provider-registry.js';
-import type { SourceCache } from '../cache/index.js';
-import type { BuildCoordinator } from '../cache/index.js';
-import type { DepCache } from '../cache/index.js';
-import type { PendingBuildTracker } from '../cache/index.js';
-import type { SecretResolver } from '../secrets/secret-resolver.js';
-import type { EnvironmentStore } from '../environments/environment-store.js';
-import type { VariableStore } from '../environments/variable-store.js';
-import type { LogStorage } from '../reporting/log-storage.js';
-import type { Kysely } from 'kysely';
-import type { Database } from '../db/types.js';
-import type { CheckMode } from '@kici-dev/engine';
+import { type ProcessingDeps } from './processor.js';
+import type { CheckMode, HostTargetSelector } from '@kici-dev/engine';
 /**
  * Input for a test trigger request.
  */
@@ -76,6 +68,17 @@ export interface TestTriggerInput {
      * Omitted means `apply`.
      */
     checkMode?: CheckMode;
+    /**
+     * Runtime host narrowing from `kici run --target`. Threaded onto the dispatch
+     * context, where it post-filters each runsOnAll job's matched roster.
+     */
+    target?: HostTargetSelector;
+    /**
+     * Raw operator-supplied `kici run --input KEY=VALUE` pairs (not coerced /
+     * defaulted). Validated + coerced + defaulted here against the matched
+     * workflow's lock dispatch descriptor before dispatch.
+     */
+    dispatchInputs?: Record<string, string>;
 }
 /**
  * Result of processing a test trigger.
@@ -91,37 +94,12 @@ interface TestTriggerResult {
     jobIds: string[];
 }
 /**
- * Dependencies for the test pipeline processor.
- * All injected for testability.
- */
-export interface TestPipelineDeps {
-    lockFileCache: LockFileCache;
-    dispatcher: Dispatcher;
-    executionTracker?: ExecutionTracker;
-    checkRunReporter?: CheckRunReporter;
-    sourceCache?: SourceCache;
-    buildCoordinator?: BuildCoordinator;
-    depCache?: DepCache;
-    pendingBuilds?: PendingBuildTracker;
-    secretResolver?: SecretResolver;
-    agentRegistry: AgentRegistry;
-    providerRegistry: ProviderRegistry;
-    /** Log storage for persisting test fixture payloads. Optional -- if not set, payload storage is skipped. */
-    logStorage?: LogStorage;
-    /** Database connection for environment protection checks. Optional. */
-    db?: Kysely<Database>;
-    /** Environment store for resolving environment ids in test dispatch parity. Optional. */
-    environmentStore?: EnvironmentStore;
-    /** Variable store for resolving environment variables in test dispatch parity. Optional. */
-    variableStore?: VariableStore;
-}
-/**
- * Process a test trigger through the existing pipeline.
+ * Process a test trigger through the shared dispatch core.
  *
- * Reuses pipeline steps starting from lock file fetch, skipping webhook
- * normalization and dedup. Supports both trigger-matched and direct
- * workflow execution modes.
+ * Resolves the lock file + matched decisions + fixture concerns, then builds a
+ * `WorkflowDispatchContext` per matched workflow and calls
+ * `dispatchMatchedWorkflow` — the same core the webhook path uses.
  */
-export declare function processTestTrigger(input: TestTriggerInput, deps: TestPipelineDeps): Promise<TestTriggerResult>;
+export declare function processTestTrigger(input: TestTriggerInput, deps: ProcessingDeps): Promise<TestTriggerResult>;
 export {};
 //# sourceMappingURL=test-pipeline.d.ts.map

package/dist/providers/github/manifest.d.ts

@@ -33,11 +33,21 @@ export interface GithubAppManifest {
     default_permissions: Record<string, string>;
     default_events: string[];
 }
+/**
+ * Validate a self-hosted webhook URL supplied via `source add github
+ * --webhook-url`. Must be a well-formed absolute `https://` URL. Returns the URL
+ * verbatim on success; throws a clear error otherwise. The validated URL is
+ * baked into `manifest.hook_attributes.url` as-is — KiCI adds no ingress and
+ * does not receive events at it; the operator owns delivery.
+ */
+export declare function validateWebhookUrl(value: string): string;
 export declare function buildGithubAppManifest(input: GithubManifestInput): GithubAppManifest;
 /** Credentials returned by GitHub's manifest-conversion endpoint. */
 export interface GithubAppCredentials {
     appId: string;
     slug: string;
+    /** GitHub's display name for the App (the authoritative stored name). */
+    name: string;
     privateKey: string;
     webhookSecret: string;
     clientId?: string;
@@ -52,6 +62,21 @@ export interface GithubAppCredentials {
 export declare function convertManifestCode(code: string, deps?: {
     octokit?: Pick<Octokit, 'request'>;
 }): Promise<GithubAppCredentials>;
+/**
+ * Ask GitHub who this App is (`GET /app`, authenticated as the App via its
+ * JWT) and return its authoritative display `name` + `slug`. This is the single
+ * "fetch the App's identity from GitHub" helper, reused at source creation, by
+ * the daily refresher, and by `kici-admin source refresh`.
+ *
+ * GitHub is the source of truth: a rename in the GitHub UI changes the value
+ * `GET /app` returns, which is what keeps the dashboard name fresh.
+ */
+export declare function fetchGithubAppIdentity(creds: Pick<GithubAppCredentials, 'appId' | 'privateKey'>, deps?: {
+    appOctokit?: Pick<Octokit, 'request'>;
+}): Promise<{
+    name: string;
+    slug: string;
+}>;
 /**
  * Poll GitHub (as the App, via a JWT) until at least one installation exists,
  * returning the first installation's id + account login. Throws on timeout.

package/dist/reporting/log-writer.d.ts

@@ -21,7 +21,26 @@ export declare class LogWriter {
     private readonly logStorage;
     private readonly observerRegistry?;
     private readonly isTestRun?;
+    /**
+     * In-flight `logStorage.append` promises, keyed by runId. `appendChunk` is
+     * called fire-and-forget from the agent WS handler (it does not await the
+     * storage write), so a run can flip to a terminal status while the final
+     * log chunk's append is still pending. `drain(runId)` lets a reader (the
+     * test-run logs cursor endpoint) wait for those pending writes before it
+     * reports the stream as fully drained — without this, the `done` flag can
+     * be returned `true` while the last user-visible log line is not yet on
+     * disk, dropping it from a blocking `kici run remote` follow.
+     */
+    private readonly pendingAppends;
     constructor(deps: LogWriterDeps);
+    /**
+     * Await every in-flight log append for `runId` that was registered before
+     * this call. Settles even if an append rejected (errors are already logged
+     * by `appendChunk`); the point is ordering, not error propagation. New
+     * appends started after this call are not waited on — a terminal run emits
+     * no further chunks, so the snapshot taken at call time is complete.
+     */
+    drain(runId: string): Promise<void>;
     /**
      * Append log lines from an agent to storage in JSONL format.
      *

package/dist/routes/admin-sources.d.ts

@@ -11,6 +11,7 @@
 import { Hono } from 'hono';
 import type { SourceStore } from '../sources/source-store.js';
 import type { Role } from '../secrets/rbac.js';
+import { type FetchGithubAppIdentity } from '../github-app-name-refresher/github-app-name-refresher.js';
 interface SourceRouteDeps {
     sourceStore: SourceStore;
     /**
@@ -39,6 +40,12 @@ interface SourceRouteDeps {
         webhookUrl: string | null;
         webhookNote?: string;
     }>;
+    /**
+     * Fetch a GitHub App's authoritative `{ name, slug }` from GitHub. Injectable
+     * for tests; defaults to the real `fetchGithubAppIdentity`. Used by the
+     * `source refresh` route.
+     */
+    fetchAppIdentity?: FetchGithubAppIdentity;
 }
 type AdminSourcesEnv = {
     Variables: {

package/dist/scaler/manager.d.ts

@@ -39,6 +39,23 @@ export interface ResolvedResources {
         memBytes: number;
     };
 }
+/**
+ * Build the scaler-usage metric rows: one per active scaler (stamped with its
+ * backend type) plus a `__global__` rollup row. Pure so it is unit-testable
+ * without constructing a full ScalerManager.
+ */
+export declare function buildScalerUsageRows(perScalerUsage: ReadonlyMap<string, {
+    cpus: number;
+    memBytes: number;
+}>, globalUsage: {
+    cpus: number;
+    memBytes: number;
+}, scalerTypeOf: (name: string) => string | undefined): Array<{
+    scaler: string;
+    scalerType?: string;
+    cpus: number;
+    memBytes: number;
+}>;
 /**
  * Status summary for metrics and health endpoints.
  */

package/dist/secrets/secret-resolver.d.ts

@@ -15,7 +15,7 @@
  * longest-path-wins uses scope path after stripping backend prefix.
  * audit log includes backend name.
  */
-import { type EnvironmentBinding, type ScopedSecret } from '@kici-dev/engine';
+import { type EnvironmentBinding, type HostFacts, type ScopedSecret } from '@kici-dev/engine';
 import type { Logger } from '@kici-dev/shared';
 import type { AuditLogger } from './audit-logger.js';
 /**
@@ -62,6 +62,21 @@ export interface ResolvedSecretMeta {
     backend: string;
     scope: string;
 }
+/**
+ * The public secret-resolution surface consumed by the dispatch path and the
+ * universal-git provider. `SecretResolver` implements this; the test adapter's
+ * `DecoratingSecretResolver` (CLI-secret overlay) implements it too, so either
+ * can flow through `ProcessingDeps.secretResolver`.
+ */
+export interface SecretResolverApi {
+    resolveForJob(orgId: string, environmentName: string, hostCtx?: HostFacts): Promise<Record<string, string>>;
+    resolveNamed(orgId: string, scope: string, key: string, opts?: {
+        store?: string;
+        runId?: string;
+        jobId?: string;
+    }): Promise<string | null>;
+    resolveForJobWithMeta(orgId: string, environmentName: string, hostCtx?: HostFacts): Promise<Record<string, ResolvedSecretMeta>>;
+}
 /**
  * Resolves secrets for a job by matching environment bindings against scoped secrets
  * from multiple backends.
@@ -71,7 +86,7 @@ export interface ResolvedSecretMeta {
  * are matched against binding patterns, and longest-path-wins uses the path AFTER
  * stripping the backend prefix.
  */
-export declare class SecretResolver {
+export declare class SecretResolver implements SecretResolverApi {
     private readonly environmentStore;
     private readonly bindingStore;
     private readonly backendStores;
@@ -83,9 +98,13 @@ export declare class SecretResolver {
      *
      * @param orgId - Organization ID
      * @param environmentName - Environment name to resolve secrets for
+     * @param hostCtx - Optional fan-out child identity for per-host resolution.
+     *   When supplied, each binding is gated by its `host_pattern` and its
+     *   `scope_pattern` is templated per-child; when omitted, only fleet-wide
+     *   (`'**'`) non-templated bindings contribute.
      * @returns Flat map of decrypted secret key-value pairs
      */
-    resolveForJob(orgId: string, environmentName: string): Promise<Record<string, string>>;
+    resolveForJob(orgId: string, environmentName: string, hostCtx?: HostFacts): Promise<Record<string, string>>;
     /**
      * Resolve a single named secret by (orgId, scope, key), optionally scoped to
      * a specific backend. Bypasses environment bindings — this is a direct
@@ -111,7 +130,7 @@ export declare class SecretResolver {
      *
      * Returns the secret value along with which backend and scope provided it.
      */
-    resolveForJobWithMeta(orgId: string, environmentName: string): Promise<Record<string, ResolvedSecretMeta>>;
+    resolveForJobWithMeta(orgId: string, environmentName: string, hostCtx?: HostFacts): Promise<Record<string, ResolvedSecretMeta>>;
     /**
      * Collect all secrets from all backend stores, prefixing scopes.
      * Per /: unreachable backends are tracked but not fatal here.
@@ -130,8 +149,17 @@ export declare class SecretResolver {
      */
     private checkScopedFailure;
     /**
-     * Find the winning secret for a given key (highest scope depth after prefix strip).
+     * Find the winning secret for a given key, mirroring the engine scope
+     * resolver's host-aware matching and `(host specificity, scope depth)`
+     * precedence so the enriched metadata reports the same secret the flat
+     * resolution selected.
      */
     private findWinningSecret;
+    /**
+     * Resolve the effective scope pattern a binding contributes for a host,
+     * applying the host gate and per-child scope templating. Mirrors the engine
+     * scope resolver's `bindingScopeForHost`. Returns `null` to skip the binding.
+     */
+    private bindingScopeForHost;
 }
 //# sourceMappingURL=secret-resolver.d.ts.map