@kici-dev/orchestrator 0.1.16 → 0.1.17

package/dist/config.d.ts

@@ -105,8 +105,6 @@ declare const configSchema: z.ZodObject<{
         production: "production";
         test: "test";
     }>>;
-    internalProviderRepoPath: z.ZodOptional<z.ZodString>;
-    internalProviderCloneUrl: z.ZodOptional<z.ZodString>;
     autoMigrate: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<boolean, string>>;
     agentMaxReconnectDelayMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     skipS3SentinelValidation: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<boolean, string>>;
@@ -262,8 +260,6 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     secretKeyFileOld?: string | undefined;
     bootstrapAdminToken?: string | undefined;
     testEventFailFirstN?: string | undefined;
-    internalProviderRepoPath?: string | undefined;
-    internalProviderCloneUrl?: string | undefined;
     otelExporterOtlpEndpoint?: string | undefined;
     clusterName?: string | undefined;
 }>;

package/dist/dashboard/handler.d.ts

@@ -13,14 +13,24 @@
  */
 import { type Kysely } from 'kysely';
 import { type ColdStore } from '@kici-dev/shared';
-import type { DashboardRunDetailRequest, DashboardRunsListRequest, DashboardRunsListResponse, DashboardRunsFiltersRequest, DashboardRunsFiltersResponse, DashboardSourcesListRequest, DashboardSourcesListResponse, DashboardStepLogsRequest, DashboardPayloadRequest, DashboardOrchLogsRequest, DashboardEventLogListRequest, DashboardEventLogDetailRequest, DashboardEventLogPayloadStreamRequest, DashboardAccessLogListRequest, DashboardEventDlqListRequest, DashboardEventDlqCountRequest, DashboardEventDlqRetryRequest, DashboardEventDlqDiscardRequest, RunRerunRequest, RunCancelRequest, ManualScheduleRequest } from '@kici-dev/engine';
+import type { DashboardRunDetailRequest, DashboardRunsListRequest, DashboardRunsListResponse, DashboardRunsFiltersRequest, DashboardRunsFiltersResponse, DashboardSourcesListRequest, DashboardSourcesListResponse, DashboardStepLogsRequest, DashboardAttestationsListRequest, DashboardPayloadRequest, DashboardOrchLogsRequest, DashboardEventLogListRequest, DashboardEventLogDetailRequest, DashboardEventLogPayloadStreamRequest, DashboardAccessLogListRequest, DashboardEventDlqListRequest, DashboardEventDlqCountRequest, DashboardEventDlqRetryRequest, DashboardEventDlqDiscardRequest, RunRerunRequest, RunCancelRequest, ManualScheduleRequest } from '@kici-dev/engine';
 import type { Database } from '../db/types.js';
 import type { LogStorage } from '../reporting/log-storage.js';
+import type { CacheStorage } from '../storage/types.js';
 import type { AccessLogWriter } from '../audit/access-log.js';
 import type { EventStore } from '../events/event-store.js';
 interface DashboardHandlerDeps {
     db: Kysely<Database>;
     logStorage: LogStorage;
+    /**
+     * Object-storage backend for provenance bundles. The attestations handler
+     * reads each stored bundle by `storage_key` and inlines it into the response
+     * so the dashboard verifies it client-side without a second fetch. Optional —
+     * when absent (e.g. orchestrators without provenance configured) the handler
+     * replies with an `error` and an empty list. Reuses the cache storage backend
+     * (the same one P1.5 writes bundles to).
+     */
+    provenanceStorage?: CacheStorage | null;
     /** Send a response message back to Platform over the WS connection. */
     send: (msg: unknown) => void;
     /** This orchestrator's instance ID, included in job detail responses. */
@@ -78,6 +88,7 @@ interface DashboardHandlerDeps {
 export declare class DashboardHandler {
     private readonly db;
     private readonly logStorage;
+    private readonly provenanceStorage;
     private readonly send;
     private readonly orchestratorId;
     private readonly accessLog;
@@ -222,7 +233,7 @@ export declare class DashboardHandler {
      *
      * `triggerTypes` is populated from `execution_runs.provider` — the
      * orchestrator has no dedicated trigger-event column, so `provider`
-     * (`github` / `generic` / `internal`) is the closest available
+     * (`github` / `generic` / `local`) is the closest available
      * discriminator the customer filter can offer.
      *
      * Attribution uses the handler-bound `orgId` / `routingKey` directly — the
@@ -251,6 +262,19 @@ export declare class DashboardHandler {
      * Looks up the step's log_path and reads content from LogStorage.
      */
     handleStepLogs(msg: DashboardStepLogsRequest): Promise<void>;
+    /**
+     * Read the attestation rows for a run, joined to `execution_jobs` for the
+     * job name. Ordered oldest-first so the dashboard table is stable.
+     */
+    private resolveAttestationsForRun;
+    /**
+     * Handle a dashboard.attestations.list request: list the run's provenance
+     * attestations, inlining each stored bundle from object storage so the
+     * dashboard verifies it client-side. Mirrors `handleStepLogs` (per-run org
+     * resolution + `recordAccess` + `send`). Rows whose bundle can't be read are
+     * skipped (best-effort) rather than failing the whole list.
+     */
+    handleAttestationsList(msg: DashboardAttestationsListRequest): Promise<void>;
     /**
      * Handle a dashboard.payload request.
      * Reads the webhook payload from log storage for the given runId.

package/dist/dashboard/needs-edges.d.ts

@@ -0,0 +1,13 @@
+import { IfFailedPolicy } from '@kici-dev/engine';
+/** A single resolved upstream dependency edge for a job. */
+export interface JobNeedEdge {
+    upstreamName: string;
+    ifFailed: IfFailedPolicy;
+}
+/** Group raw execution_job_needs rows by downstream job_name. */
+export declare function groupNeedsByJobName(rows: ReadonlyArray<{
+    job_name: string;
+    upstream_name: string;
+    if_failed: string;
+}>): Map<string, JobNeedEdge[]>;
+//# sourceMappingURL=needs-edges.d.ts.map

package/dist/db/migrations/035_pending_workflow_contexts.d.ts

@@ -0,0 +1,11 @@
+import { type Kysely } from 'kysely';
+/**
+ * Pending workflow dispatch context — backs resume of a workflow whose install
+ * gate held. One row per held run: the serializable dispatch inputs needed to
+ * rebuild the WorkflowDispatchContext when the hold releases (reviewer approve,
+ * wait-timer expiry, concurrency slot free). The row is deleted once the resume
+ * dispatch has been kicked off.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=035_pending_workflow_contexts.d.ts.map

package/dist/db/migrations/036_attestations.d.ts

@@ -0,0 +1,15 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add the `attestations` table for build-provenance bundles.
+ *
+ * When a workflow step calls `ctx.attestProvenance`, the agent uploads the
+ * signed KiCI bundle to object storage under
+ * `provenance/{run_id}/{job_id}/{subject_digest}.kici.json` and the
+ * orchestrator records one row here so the dashboard can list and fetch
+ * attestations per run/job.
+ *
+ * Idempotent: a re-run on a DB that already has the table is a no-op.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=036_attestations.d.ts.map

package/dist/db/migrations/037_generic_sources_provider_type_local.d.ts

@@ -0,0 +1,19 @@
+import { type Kysely } from 'kysely';
+/**
+ * Replace the `generic_webhook_sources.provider_type` CHECK constraint so it
+ * permits `'local'` instead of `'internal'`, and migrate any carried-over
+ * `'internal'` rows to `'local'`.
+ *
+ * The local filesystem (`file://`) provider is `provider_type='local'`; the
+ * value used to be `'internal'`. The original CHECK constraint
+ * (`generic_webhook_sources_provider_type_check`) allowed only
+ * `{'generic','internal'}`, so writing a `'local'` row fails. Universal-git
+ * sources keep `provider_type='generic'` (discriminated by `git_config`), so
+ * the new allowed set is `{'generic','local'}`.
+ *
+ * Idempotent: the constraint is dropped IF EXISTS and recreated; the data
+ * backfill is a plain UPDATE that is a no-op once no `'internal'` rows remain.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=037_generic_sources_provider_type_local.d.ts.map

package/dist/db/migrations/038_remote_sources.d.ts

@@ -0,0 +1,14 @@
+import { type Kysely } from 'kysely';
+/**
+ * `remote_sources` anchors a Platform-relayed `kici run remote` to its real
+ * org. One row per org served by this orchestrator: routing key
+ * `remote:<orgId>` maps to the canonical org id, so `resolveOrgId` resolves
+ * the real tenant through the same local-source path a webhook takes — no
+ * GitHub App, no webhook secret, no manual setup. The row is auto-provisioned
+ * on Platform auth from the canonical org id carried on `auth.success`.
+ *
+ * Idempotent: a re-run on a DB that already has the table is a no-op.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=038_remote_sources.d.ts.map

package/dist/db/types.d.ts

@@ -39,6 +39,7 @@ export interface Database {
     org_settings: OrgSettingsTable;
     execution_job_needs: ExecutionJobNeedsTable;
     pending_job_contexts: PendingJobContextsTable;
+    pending_workflow_contexts: PendingWorkflowContextsTable;
     event_log: EventLogTable;
     access_log: AccessLogTable;
     cold_store_chunk_counts: ColdStoreChunkCountsTable;
@@ -47,6 +48,8 @@ export interface Database {
     scaler_spawning_agents: ScalerSpawningAgentsTable;
     scaler_agent_jobs: ScalerAgentJobsTable;
     scaler_reservations: ScalerReservationsTable;
+    attestations: AttestationsTable;
+    remote_sources: RemoteSourcesTable;
 }
 /**
  * Cluster metadata table
@@ -925,15 +928,17 @@ export interface GenericWebhookSourceTable {
     deleted_at: Date | null;
     /** Provider implementation to route this source through.
      *  'generic' (default) → GenericWebhookNormalizer (Stripe-shaped payloads).
-     *  'internal' → InternalWebhookNormalizer (github-shaped push/PR payloads
-     *  for E2E tests and the staging smoke test). */
+     *  'local' → LocalWebhookNormalizer (github-shaped push/PR payloads for a
+     *  git repository present on the agent filesystem, cloned via file://). */
     provider_type: Generated<string>;
-    /** Universal-git config (JSONB) for sources that also know how to build
-     *  clone URLs, fetch lock files, and issue clone credentials against a
-     *  user-supplied git server (Forgejo / Gitea / Gogs / GitLab repo-webhook /
-     *  plain GitHub repo-webhook). null for legacy generic / internal sources
-     *  that don't drive git operations. Shape validated by
-     *  `UniversalGitConfigSchema` at the application layer. */
+    /** Git config (JSONB), dual-purpose discriminated by `provider_type`:
+     *  - universal-git sources ('generic' with git_config) store a
+     *    `UniversalGitConfig` (clone URLs, lock-file fetch, clone credentials
+     *    against Forgejo / Gitea / Gogs / GitLab repo-webhook / GitHub repo).
+     *  - local sources ('local') store a `LocalSourceConfig`
+     *    (`{ repoBasePath, cloneUrlBase? }`).
+     *  null for plain generic sources that don't drive git operations. Shape
+     *  validated by the matching Zod schema at the application layer. */
     git_config: ColumnType<string | Record<string, unknown> | null, string | null, string | null>;
 }
 export type GenericWebhookSource = Selectable<GenericWebhookSourceTable>;
@@ -1271,6 +1276,24 @@ export interface PendingJobContextsTable {
 }
 export type PendingJobContextRow = Selectable<PendingJobContextsTable>;
 export type NewPendingJobContext = Insertable<PendingJobContextsTable>;
+/**
+ * Pending workflow dispatch contexts table.
+ * Persists the serializable WorkflowDispatchContext inputs needed to resume a
+ * workflow whose install gate held. One row per held run (keyed by run_id).
+ * Created at hold time, deleted once the resume dispatch is kicked off.
+ */
+export interface PendingWorkflowContextsTable {
+    /** Run identifier (one pending dispatch per run) */
+    run_id: string;
+    /** Organization id */
+    org_id: string;
+    /** Serializable WorkflowDispatchContext inputs as JSONB */
+    context: ColumnType<Record<string, unknown>, string, string>;
+    /** When this context was stored */
+    created_at: Generated<Date>;
+}
+export type PendingWorkflowContextRow = Selectable<PendingWorkflowContextsTable>;
+export type NewPendingWorkflowContext = Insertable<PendingWorkflowContextsTable>;
 /**
  * Inbound webhook delivery event log table.
  * One row per inbound webhook delivery (relay or direct), regardless of
@@ -1289,7 +1312,7 @@ export interface EventLogTable {
     org_id: string;
     /** Provider delivery ID (unique within org) */
     delivery_id: string;
-    /** Routing key (e.g. "github:42", "generic:<org>:<src>", "internal:...") */
+    /** Routing key (e.g. "github:42", "generic:<org>:<src>") */
     routing_key: string;
     /** Provider event name (X-GitHub-Event / X-Event-Type / 'default') */
     event: string;
@@ -1297,7 +1320,7 @@ export interface EventLogTable {
     action: string | null;
     /** Where the delivery arrived: 'relay' (Platform WS) or 'direct' (HTTP) */
     source: string;
-    /** Provider type ('github' / 'generic' / 'internal') */
+    /** Provider type ('github' / 'generic' / 'local') */
     provider: string;
     /** owner/repo when extractable */
     repo_identifier: string | null;
@@ -1456,6 +1479,56 @@ export interface CheckRunTrackingTable {
 export type CheckRunTrackingRow = Selectable<CheckRunTrackingTable>;
 export type NewCheckRunTrackingRow = Insertable<CheckRunTrackingTable>;
 export type CheckRunTrackingUpdate = Updateable<CheckRunTrackingTable>;
+/**
+ * Build-provenance attestation table.
+ *
+ * One row per `ctx.attestProvenance` bundle uploaded to object storage. The
+ * dashboard lists/fetches attestations by `(run_id, job_id)`.
+ */
+export interface AttestationsTable {
+    /** Random id (primary key). */
+    id: string;
+    /** KiCI run this attestation belongs to. */
+    run_id: string;
+    /** KiCI job this attestation was produced by. */
+    job_id: string;
+    /** Caller-supplied artifact name (e.g. an npm package coordinate). */
+    subject_name: string;
+    /** Primary subject digest (lowercase hex) used in the storage key. */
+    subject_digest: string;
+    /** Object-storage key the bundle was written to. */
+    storage_key: string;
+    /** Signing mode ('kici' for Mode A). */
+    mode: string;
+    /** Bundle media type. */
+    media_type: string;
+    /** When this row was inserted. */
+    created_at: Generated<Date>;
+}
+export type AttestationRow = Selectable<AttestationsTable>;
+export type NewAttestationRow = Insertable<AttestationsTable>;
+/**
+ * Remote-source table (remote_sources).
+ *
+ * Anchors a Platform-relayed `kici run remote` to its real org: routing key
+ * `remote:<orgId>` maps to the canonical org id so `resolveOrgId` resolves the
+ * real tenant through the same local-source path a webhook takes. One row per
+ * org served by this orchestrator, auto-provisioned on Platform auth.
+ */
+export interface RemoteSourcesTable {
+    /** Canonical org id (`org_<…>`) this anchor resolves to. */
+    customer_id: string;
+    /** Deterministic routing key `remote:<orgId>`. */
+    routing_key: string;
+    /** Cluster id this orchestrator deployment reports, or null. */
+    cluster_id: string | null;
+    /** When this row was first provisioned. */
+    created_at: Generated<Date>;
+    /** When this row was last upserted. */
+    updated_at: Generated<Date>;
+}
+export type RemoteSourceRow = Selectable<RemoteSourcesTable>;
+export type NewRemoteSourceRow = Insertable<RemoteSourcesTable>;
 /**
  * Scaler spawning-agents table (scaler_spawning_agents).
  *

package/dist/diagnostics/fleet-collector.d.ts

@@ -13,8 +13,8 @@ import { z } from 'zod';
 export declare const FleetNodeStatus: z.ZodEnum<{
     error: "error";
     ok: "ok";
-    timeout: "timeout";
     unreachable: "unreachable";
+    timeout: "timeout";
 }>;
 export type FleetNodeStatus = z.infer<typeof FleetNodeStatus>;
 export interface FleetCollectorDeps {

package/dist/entry-helpers.d.ts

@@ -5,14 +5,13 @@
  * Both entry points import these helpers instead of maintaining separate copies.
  */
 import { type SourceProvider, SourceSubtype } from '@kici-dev/engine';
-import { ProviderRegistry } from './provider-registry.js';
 /**
  * A provider source for Platform registration.
  *
  * `provider` is the coarse-grained Platform-routing family (`github` /
  * `gitlab` / `bitbucket` / `generic`). `subtype` is the fine-grained
  * source kind that survives all the way to the dashboard so universal-git,
- * generic_webhook, and internal sources stay distinguishable. `name` is
+ * generic_webhook, and local sources stay distinguishable. `name` is
  * the human-readable label shown in the runs view + sources tab.
  */
 export interface ProviderSource {
@@ -50,24 +49,6 @@ export declare function diffProviderSources(oldSources: ProviderSource[], newSou
     added: ProviderSource[];
     removed: ProviderSource[];
 };
-/**
- * Register the internal provider bundle for E2E testing when the
- * `internalProviderRepoPath` config field (KICI_INTERNAL_PROVIDER_REPO_PATH)
- * is set.
- *
- * When the field is present, this overwrites the previously-registered
- * `generic:default` bundle with one that has a lockFileFetcher and
- * repoUrlBuilder (needed for the webhook pipeline to match triggers and
- * dispatch jobs).
- *
- * When the field is not set, does nothing (leaves `generic:default` as-is).
- *
- * @returns true if the internal provider was registered, false otherwise
- */
-export declare function registerInternalProviderIfConfigured(registry: ProviderRegistry, config: {
-    internalProviderRepoPath?: string;
-    internalProviderCloneUrl?: string;
-}): boolean;
 /**
  * Decide whether the local orchestrator can serve a `generic_webhook_sources`
  * row with the given `provider_type`. Used at boot (and any future reload) to
@@ -79,15 +60,12 @@ export declare function registerInternalProviderIfConfigured(registry: ProviderR
  * - `'generic'` / `'universal-git'` → always servable (the bundles register
  *   without filesystem dependencies; per-row failures during universal-git
  *   bundle registration are already isolated in orchestrator-core.ts).
- * - `'internal'` → only servable when `internalProviderRepoPath` is set, the
- *   path exists on disk, and is a directory. This mirrors the fail-fast
- *   guard in `registerInternalProviderIfConfigured`. The check is binary
- *   per peer: a single `KICI_INTERNAL_PROVIDER_REPO_PATH` backs every
- *   internal source on that peer (per-source `repoIdentifier`s nest under
- *   the same base dir).
+ * - `'local'` → only servable when the ROW's own `git_config.repoBasePath`
+ *   exists as a directory on THIS peer. The check is per-source and per-peer:
+ *   a local repo present on one HA peer may be absent on another, so only the
+ *   peer that hosts the repo advertises the routing key. Mirrors the statSync
+ *   gate in `registerProviderBundleForSource`.
  * - Any unknown provider_type returns false to fail closed.
  */
-export declare function canServeGenericProviderType(providerType: string, config: {
-    internalProviderRepoPath?: string;
-}): boolean;
+export declare function canServeGenericProviderType(providerType: string, gitConfig?: string | Record<string, unknown> | null): boolean;
 //# sourceMappingURL=entry-helpers.d.ts.map

package/dist/environments/held-runs.d.ts

@@ -45,6 +45,12 @@ export interface CreateHoldData {
     environmentId?: string | null;
     /** Queue type: 'environment' (default) or 'security'. */
     queueType?: 'environment' | 'security';
+    /**
+     * Held-run `hold_type` discriminator. Defaults to `'approval'` (reviewer
+     * holds). The workflow install gate sets `'wait_timer'` / `'concurrency'` so
+     * the automated release sweeps can find their rows.
+     */
+    holdType?: string;
 }
 /** A single decision to record against a hold. */
 export interface RecordDecisionData {
@@ -121,6 +127,24 @@ export declare class HeldRunStore {
      * holds notify the waiting agent; job/workflow holds fail the run).
      */
     listOverdue(): Promise<HeldRun[]>;
+    /**
+     * Release overdue workflow `wait_timer` holds. The install-gate wait action
+     * pauses the workflow as a held run; on timer expiry it must RESUME (not
+     * fail like a reviewer-hold expiry). Flips each overdue pending
+     * `hold_type='wait_timer'`, `hold_scope='workflow'` row to `released` and
+     * returns a `ReleaseSignal` per row so the caller can resume the workflow.
+     * Runs BEFORE `expireOverdue()` so these rows leave the pending pool before
+     * the expire-and-fail sweep sees them.
+     */
+    releaseDueWaitHolds(): Promise<ReleaseSignal[]>;
+    /**
+     * Release the oldest pending workflow `concurrency` hold for a group. Called
+     * when a concurrency slot frees on run completion. Flips the oldest matching
+     * pending row to `released` and returns its `ReleaseSignal`, or null when no
+     * concurrency hold is queued for the group. `group` matches the held row's
+     * `environment_id` (workflow-level install concurrency keys on the env id).
+     */
+    releaseConcurrencyHold(orgId: string, group: string): Promise<ReleaseSignal | null>;
     /**
      * Expire overdue pending runs. Called by the stale detector.
      * Sets status to 'expired' and resolved_at to now() for all

package/dist/index.js

@@ -991,6 +991,7 @@ const DEFAULT_EXPIRY_DAYS = 90;
 * Used by the coordinator to manage credentials for all cluster members.
 */
 var PeerCredentialStore = class {
+	db;
 	constructor(db) {
 		this.db = db;
 	}

package/dist/metrics/prometheus.d.ts

@@ -264,6 +264,8 @@ export declare const InstallSecretsDecisionReason: {
     readonly ProtectionRuleBlock: "protection_rule_block";
     readonly MissingToken: "missing_token";
     readonly MissingInstallEnv: "missing_install_env";
+    /** A protection gate held the workflow install (hold / wait / queue). */
+    readonly Held: "held";
 };
 export type InstallSecretsDecisionReason = (typeof InstallSecretsDecisionReason)[keyof typeof InstallSecretsDecisionReason];
 /**
@@ -280,8 +282,8 @@ export type InstallSecretsChannel = (typeof InstallSecretsChannel)[keyof typeof
  * Total install-secrets resolution decisions.
  *
  * Labels:
- * - decision: pass | reject
- * - reason: ok (only with `pass`), or one of the reject reasons enumerated in `InstallSecretsDecisionReason`
+ * - decision: pass | reject | hold
+ * - reason: ok (only with `pass`), held (only with `hold`), or one of the reject reasons enumerated in `InstallSecretsDecisionReason`
  *
  * Pass series are emitted exactly once per resolver call that does any work
  * (workflows declaring neither `registries:` nor `installEnv:` are NOT

package/dist/orchestrator-core.d.ts

@@ -210,6 +210,54 @@ export interface OrchestratorHooks {
      */
     startupLogMessage: (port: number) => string;
 }
+/**
+ * Normalize a lock job's `needs` array (strings, NeedsEntry objects, or
+ * NeedsGroupEntry objects) to the set of upstream BASE job names. Group entries
+ * are skipped here — group fan-in is resolved separately by the scheduler.
+ */
+export declare function upstreamBaseNamesFromNeeds(needs: unknown): string[];
+/**
+ * Build the downstream `upstreamJobOutputs` map keyed by BASE name. A base name
+ * that fanned into matrix children (rows with `matrix_values`) gets the
+ * `{ byMatrix, merged }` envelope; a single non-fanned row keeps the flat shape.
+ * Returns undefined when no upstream produced outputs.
+ */
+export declare function buildUpstreamOutputsByBase(baseNames: string[], rows: Array<{
+    job_name: string;
+    outputs: unknown;
+    matrix_values: unknown;
+}>): Record<string, Record<string, unknown>> | undefined;
+/**
+ * Group an upstream's child rows into the matrix outputs envelope
+ * `{ byMatrix: { '<suffix>': outputs }, merged: <last-write-wins> }`. The suffix
+ * is the text inside the `(...)` of each expanded child name; children are
+ * merged in name order (deterministic, matching dispatch order).
+ */
+export declare function buildMatrixOutputsEnvelope(baseName: string, children: Array<{
+    job_name: string;
+    parsed: Record<string, unknown>;
+}>): {
+    byMatrix: Record<string, Record<string, unknown>>;
+    merged: Record<string, unknown>;
+};
+/**
+ * Merge plain `outputs` and decrypted `secret outputs` from upstream jobs
+ * into the dispatch envelope's `secrets` + `upstreamJobOutputs` fields.
+ *
+ * For a fanned (matrix) upstream, the downstream sees a keyed envelope
+ * `{ byMatrix: { '<suffix>': outputs }, merged: <last-write-wins> }` under the
+ * BASE name; a non-fanned upstream keeps the flat outputs shape.
+ *
+ * The needs-aware scheduler guarantees upstreams are
+ * terminal before the downstream is dispatched, so the lookups below
+ * always find final values. Errors are swallowed (warn-logged) so a flaky
+ * upstream-outputs read doesn't block dispatch — the agent will still get
+ * its declared secrets, just without the merged upstream additions.
+ */
+export declare function mergeUpstreamOutputs(db: Kysely<Database>, runId: string, jobName: string, needs: unknown, dispatchSecrets: Record<string, string> | undefined, secretKey: string): Promise<{
+    mergedSecrets: Record<string, string> | undefined;
+    upstreamJobOutputs: Record<string, Record<string, unknown>> | undefined;
+}>;
 export declare function bootstrapOrchestrator(config: AppConfig, hooks: OrchestratorHooks, options?: {
     otelSdk?: {
         shutdown(): Promise<void>;

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

@@ -91,6 +91,23 @@ export interface WorkflowDispatchContext {
 export interface DispatchMatchedWorkflowResult {
     /** Number of jobs successfully dispatched (non-rejected). */
     dispatchedJobCount: number;
+    /** True when the workflow install gate paused the dispatch (held run). */
+    held?: boolean;
+}
+/** Options controlling a (re-)dispatch of a matched workflow. */
+export interface DispatchMatchedWorkflowOptions {
+    /**
+     * Resume path: skip the workflow install protection gate (already satisfied)
+     * so secrets resolve directly and the dispatch flows into job dispatch.
+     */
+    skipInstallProtectionGate?: boolean;
+    /** The released held-run id being resumed (for logging / correlation). */
+    reuseHeldRunId?: string;
+    /**
+     * The run id whose `held` execution_runs row should be reused (flipped to
+     * pending) instead of inserting a fresh row.
+     */
+    reuseRunId?: string;
 }
 /**
  * Dispatch a single matched workflow.
@@ -107,5 +124,5 @@ export interface DispatchMatchedWorkflowResult {
  *   I. deferred init dispatch (fire-and-forget per job)
  *   J. deferred dynamic dispatch (fire-and-forget per dynamic entry)
  */
-export declare function dispatchMatchedWorkflow(ctx: WorkflowDispatchContext): Promise<DispatchMatchedWorkflowResult>;
+export declare function dispatchMatchedWorkflow(ctx: WorkflowDispatchContext, opts?: DispatchMatchedWorkflowOptions): Promise<DispatchMatchedWorkflowResult>;
 //# sourceMappingURL=dispatch-matched-workflow.d.ts.map

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

@@ -8,10 +8,13 @@
  *
  *   1. Parses every qualified ref and groups by environment name.
  *   2. Fires the per-environment protection-rule pipeline once per unique env
- *      (branch / trust / concurrency / reviewer / wait-timer). Any non-pass
- *      result rejects the whole workflow dispatch — v1 does not yet support
- *      workflow-scoped held-runs, so a `hold` from the reviewer-gate is
- *      surfaced as a reject with a clear reason.
+ *      (branch / trust / concurrency / reviewer / wait-timer). A `reject`
+ *      result fails the whole workflow dispatch with a clear reason; a
+ *      `hold` / `wait` / `queue` result returns a structured `hold` decision
+ *      so the caller can pause the workflow dispatch as a workflow-scoped held
+ *      run and resume it when the gate clears. On the resume path the caller
+ *      sets `skipProtectionGate` so the gate (already satisfied) is bypassed
+ *      and secrets are resolved directly.
  *   3. Resolves secrets per environment via `secretResolver.resolveForJob`
  *      (which writes its own audit log lines).
  *   4. Validates each registry URL scheme: HTTPS always allowed; `http://`
@@ -26,7 +29,7 @@
  * Pure helper: no imports of the dispatch giant. Tested in isolation in
  * `install-secrets-resolver.test.ts`.
  */
-import type { LockRegistry } from '@kici-dev/engine';
+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 { EnvironmentStore } from '../environments/environment-store.js';
@@ -47,6 +50,18 @@ export interface ResolveInstallSecretsArgs {
     environmentStore: EnvironmentStore | undefined;
     secretResolver: SecretResolver | undefined;
     protectionContext: JobDispatchContext;
+    /**
+     * Resume path: skip the protection-rule gate (already satisfied) and resolve
+     * secrets directly. The untrusted-contributor strip still runs first.
+     */
+    skipProtectionGate?: boolean;
+}
+/** Normalized requirement carried on a `hold` decision. */
+export interface InstallHoldRequirement {
+    clauses: ApproverClause[];
+    /** ISO timestamp after which the hold expires. */
+    expiresAt: string;
+    reason: string;
 }
 export type ResolveInstallSecretsResult = {
     decision: 'pass';
@@ -56,6 +71,18 @@ export type ResolveInstallSecretsResult = {
 } | {
     decision: 'reject';
     reason: string;
+} | {
+    decision: 'hold';
+    /** The gate action that paused the dispatch. */
+    action: 'hold' | 'wait' | 'queue';
+    /** The environment whose install gate held. */
+    envName: string;
+    /** Resolved environment id (for the held row). */
+    environmentId: string;
+    /** Discriminates the release trigger: 'reviewer' | 'wait_timer' | 'concurrency' | 'security'. */
+    holdType: string;
+    queueType: 'environment' | 'security';
+    requirement: InstallHoldRequirement;
 };
 /** Parse `<environment>:<secret-name>`. Returns null on malformed input. */
 export declare function parseQualifiedSecretRef(ref: string): {

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

@@ -19,25 +19,28 @@
  */
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
-import type { NeedsEntry, NeedsGroupEntry } from '@kici-dev/engine';
+import type { MaterializedJob } from '@kici-dev/engine';
 /** Result of evaluating downstream jobs after an upstream completes. */
 export interface SchedulerResult {
     jobName: string;
     action: 'dispatch' | 'skip';
     reason?: string;
 }
-/** Minimal lock job shape needed by insertEdgesForRun. */
-interface LockJobLike {
-    readonly name: string;
-    readonly needs: readonly (string | NeedsEntry | NeedsGroupEntry)[];
-    readonly dependsOnGroups?: readonly string[];
-}
 /**
  * Insert dependency edges at run start for static-to-static needs.
+ *
+ * Operates on materialized jobs (matrix-expanded children) and an expansion map
+ * (base job name -> the expanded child names). An upstream reference to a base
+ * name `test` that fanned into `test (a)` / `test (b)` produces one edge per
+ * child, so a downstream `needs: ['test']` waits for ALL children to terminate.
+ * Each materialized child likewise inherits the full upstream edge set under its
+ * own expanded name.
+ *
  * NeedsGroupEntry items are skipped (resolved later via resolveGroupEdges).
- * Root jobs (no needs, no dependsOnGroups) are marked needs_satisfied=true.
+ * Root jobs (no needs, no dependsOnGroups) are marked needs_satisfied=true,
+ * keyed by expanded name.
  */
-export declare function insertEdgesForRun(db: Kysely<Database>, runId: string, lockJobs: readonly LockJobLike[]): Promise<void>;
+export declare function insertEdgesForRun(db: Kysely<Database>, runId: string, jobs: readonly MaterializedJob[], expansionMap: ReadonlyMap<string, readonly string[]>): Promise<void>;
 /**
  * Resolve dynamic group edges after eval completion.
  *
@@ -81,5 +84,4 @@ export declare function checkSchedulerInvariant(db: Kysely<Database>, runId: str
  * due to failure propagation. Only follows edges where if_failed='skip'.
  */
 export declare function getFailurePropagationTargets(db: Kysely<Database>, runId: string, failedJobName: string): Promise<string[]>;
-export {};
 //# sourceMappingURL=needs-scheduler.d.ts.map