@kici-dev/orchestrator 0.1.15 → 0.1.17

package/dist/cluster/peer-client.d.ts

@@ -10,7 +10,7 @@
  * Authentication uses ECDH key exchange followed by join token (first connect)
  * or HMAC credential proof (reconnection).
  */
-import { type PeerHeartbeat, type PeerToPeerMessage, type JobReroute, type JobProgress, type PeerJobCancel, type PeerLogChunk, type PeerCacheUploadRequest, type PeerCacheUploadResponse, type PeerConfigReload, type PeerConfigReloadResponse, type PeerLeaving, type PeerAgentTokenRevoke, type RaftVoteRequest, type RaftVoteResponse, type RaftAppendEntries } from '@kici-dev/engine';
+import { type PeerHeartbeat, type PeerToPeerMessage, type JobReroute, type JobProgress, type PeerJobCancel, type PeerLogChunk, type PeerCacheUploadRequest, type PeerCacheUploadResponse, type PeerConfigReload, type PeerConfigReloadResponse, type PeerLogsCollectRequest, type PeerLeaving, type PeerAgentTokenRevoke, type RaftVoteRequest, type RaftVoteResponse, type RaftAppendEntries } from '@kici-dev/engine';
 import type { PeerRegistry } from './peer-registry.js';
 type PeerConnectionState = 'disconnected' | 'connecting' | 'handshaking' | 'authenticating' | 'connected';
 export interface PeerClientOptions {
@@ -78,7 +78,20 @@ export interface PeerClientOptions {
      * Platform-mediated discovery dedupes against the same client.
      */
     onAuthenticated?: (targetInstanceId: string) => void;
+    /**
+     * Callback when a peer.logs.collect.request is received from the peer. Builds
+     * this node's subtree bundle and streams it back via the supplied `send`
+     * (peer.logs.collect.chunk frames, or a peer.logs.collect.error on failure).
+     * If undefined, incoming collect requests are ignored.
+     */
+    onLogsCollectRequest?: PeerLogsCollectResponder;
 }
+/**
+ * Builds a node's subtree bundle in response to a peer.logs.collect.request and
+ * streams it back through `send`. Shared by PeerClient (outgoing-dialed peers)
+ * and the peer handler (incoming-dialed peers).
+ */
+export type PeerLogsCollectResponder = (msg: PeerLogsCollectRequest, send: (out: PeerToPeerMessage) => boolean) => Promise<void>;
 export declare class PeerClient {
     private ws;
     private _state;
@@ -91,6 +104,8 @@ export declare class PeerClient {
     private readonly ackWaiters;
     private readonly cacheWaiters;
     private readonly configReloadWaiters;
+    /** Correlates peer.logs.collect.request with the peer's chunked subtree response. */
+    private readonly logsCollectWaiters;
     private readonly url;
     private readonly joinToken?;
     private readonly credentialFile;
@@ -112,6 +127,7 @@ export declare class PeerClient {
     private readonly onAgentTokenRevoke?;
     private readonly onPeerConfigReload?;
     private readonly onAuthenticated?;
+    private readonly onLogsCollectRequest?;
     constructor(options: PeerClientOptions);
     /** Current connection state. */
     get state(): PeerConnectionState;
@@ -150,6 +166,12 @@ export declare class PeerClient {
      *   if the peer doesn't reply within the timeout.
      */
     sendConfigReloadAndWait(msg: PeerConfigReload, timeoutMs?: number): Promise<PeerConfigReloadResponse | null>;
+    /**
+     * Send a peer.logs.collect.request to the connected peer and await its
+     * reassembled subtree-bundle ZIP. Rejects on timeout, an error frame, or
+     * peer disconnect.
+     */
+    sendLogsCollectAndWait(msg: PeerLogsCollectRequest, timeoutMs: number): Promise<Buffer>;
     /**
      * Send a cache upload request to the coordinator and wait for a response
      * with a pre-signed URL.

package/dist/cluster/peer-handler.d.ts

@@ -6,7 +6,7 @@
  * proof (reconnection), registers the peer in PeerRegistry, and routes
  * messages bidirectionally. Sends periodic heartbeats to the connecting peer.
  */
-import { type PeerHeartbeat, type PeerToPeerMessage, type JobReroute, type JobProgress, type PeerScalerEvent, type PeerJobCancel, type PeerLogChunk, type PeerCacheUploadRequest, type PeerCacheUploadResponse, type PeerConfigReload, type PeerConfigReloadResponse, type PeerLeaving, type PeerAgentTokenRevoke, type RaftVoteRequest, type RaftVoteResponse, type RaftAppendEntries } from '@kici-dev/engine';
+import { type PeerHeartbeat, type PeerToPeerMessage, type JobReroute, type JobProgress, type PeerScalerEvent, type PeerJobCancel, type PeerLogChunk, type PeerCacheUploadRequest, type PeerCacheUploadResponse, type PeerConfigReload, type PeerConfigReloadResponse, type PeerLogsCollectRequest, type PeerLeaving, type PeerAgentTokenRevoke, type RaftVoteRequest, type RaftVoteResponse, type RaftAppendEntries } from '@kici-dev/engine';
 import type { PeerRegistry } from './peer-registry.js';
 import type { PeerCredentialStore } from './peer-credentials.js';
 import { type JoinTokenManager } from './join-token.js';
@@ -78,6 +78,13 @@ export interface PeerHandlerDeps {
         restartRequired?: string[];
         fieldsChanged?: string[];
     }>;
+    /**
+     * Callback when a peer.logs.collect.request arrives from an incoming-dialed
+     * peer. Builds this node's subtree bundle and streams it back through `send`
+     * (peer.logs.collect.chunk frames, or a peer.logs.collect.error on failure).
+     * If undefined, incoming collect requests are ignored.
+     */
+    onLogsCollectRequest?: (msg: PeerLogsCollectRequest, send: (out: PeerToPeerMessage) => boolean) => Promise<void>;
 }
 /**
  * Create a handler function for incoming peer WebSocket connections.
@@ -90,6 +97,7 @@ export declare function createPeerHandler(deps: PeerHandlerDeps): {
     sendToPeer: (targetInstanceId: string, msg: PeerToPeerMessage) => boolean;
     sendAndWaitAck: (targetInstanceId: string, msg: JobReroute, timeoutMs?: number) => Promise<boolean>;
     sendConfigReloadAndWait: (targetInstanceId: string, msg: PeerConfigReload, timeoutMs?: number) => Promise<PeerConfigReloadResponse | null>;
+    sendLogsCollectAndWait: (targetInstanceId: string, msg: PeerLogsCollectRequest, timeoutMs: number) => Promise<Buffer>;
     getConnectionCount: () => number;
     broadcastHeartbeat: (inventory: Omit<PeerHeartbeat, "type">) => void;
     broadcastAgentTokenRevoke: (msg: PeerAgentTokenRevoke) => void;

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/033_org_settings_approval.d.ts

@@ -0,0 +1,19 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add the two approval-policy columns to `org_settings`:
+ *
+ * - `approval_expiry_seconds INTEGER NOT NULL DEFAULT 86400` — how long a held
+ *   approval element waits before it expires (and its run/job/step is
+ *   rejected). One day by default. An SDK `requireApproval` `timeout` overrides
+ *   this per element; otherwise this per-org value applies.
+ * - `allow_self_approval BOOLEAN NOT NULL DEFAULT true` — whether the user who
+ *   triggered a run may also approve its held elements. Operators turn it off
+ *   to enforce four-eyes review.
+ *
+ * Both are cluster-configurable per org via `kici-admin org-settings approval`
+ * and the orchestrator admin route. Idempotent: a re-run on a DB that already
+ * has the columns is a no-op (each column is guarded independently).
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=033_org_settings_approval.d.ts.map

package/dist/db/migrations/034_held_runs_generalize.d.ts

@@ -0,0 +1,24 @@
+import { type Kysely } from 'kysely';
+/**
+ * Generalize `held_runs` from an environment-only hold into the unified
+ * "held element" model that backs per-element approvals, and add the
+ * `held_run_approvals` table that records each approver's decision.
+ *
+ * New `held_runs` columns (all idempotent, column-exists guarded):
+ * - `hold_scope text NOT NULL DEFAULT 'job'` — 'workflow' | 'job' | 'step'
+ *   (engine `HoldScope`). Existing rows held a single job, so they default to
+ *   'job'.
+ * - `step_index integer` — nullable; set only for step-scoped holds.
+ * - `trigger_source text NOT NULL DEFAULT 'environment'` — 'environment' |
+ *   'explicit' (engine `TriggerSource`). Existing holds came from environment
+ *   protection, so they default to 'environment'.
+ * - `approval_requirement jsonb` — the normalized `ApprovalRequirement`
+ *   (clauses + expiresAt + reason) the hold must satisfy. Nullable for legacy
+ *   rows that predate the approval model.
+ *
+ * New `held_run_approvals` table: one row per approver decision, FK to
+ * `held_runs.id` (uuid) with ON DELETE CASCADE.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=034_held_runs_generalize.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

@@ -1,5 +1,5 @@
 import type { ColumnType, Generated, Insertable, Selectable, Updateable } from 'kysely';
-import type { InitFailure } from '@kici-dev/engine';
+import type { ApprovalRequirement, ApproverClause, InitFailure } from '@kici-dev/engine';
 /**
  * PostgreSQL-only database types.
  * Column names use snake_case matching the actual database column names.
@@ -19,6 +19,7 @@ export interface Database {
     environment_variables: EnvironmentVariablesTable;
     environment_source_overrides: EnvironmentSourceOverridesTable;
     held_runs: HeldRunsTable;
+    held_run_approvals: HeldRunApprovalsTable;
     admin_tokens: AdminTokenTable;
     agent_tokens: AgentTokenTable;
     config_versions: ConfigVersionTable;
@@ -38,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;
@@ -46,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
@@ -630,10 +634,49 @@ export interface HeldRunsTable {
     expires_at: Date;
     /** When this hold was resolved */
     resolved_at: Date | null;
+    /**
+     * Hold granularity: 'workflow' | 'job' | 'step' (engine `HoldScope`).
+     * Existing environment holds are job-scoped, hence the 'job' default.
+     */
+    hold_scope: Generated<string>;
+    /** Step index within the job for step-scoped holds; null otherwise. */
+    step_index: number | null;
+    /**
+     * What created the hold: 'environment' (mandatory env policy) | 'explicit'
+     * (SDK `requireApproval`). Engine `TriggerSource`.
+     */
+    trigger_source: Generated<string>;
+    /**
+     * Normalized `ApprovalRequirement` (clauses + expiresAt + reason) the hold
+     * must satisfy. Null for legacy rows that predate the approval model.
+     */
+    approval_requirement: ColumnType<ApprovalRequirement | null, ApprovalRequirement | string | null | undefined, ApprovalRequirement | string | null>;
 }
 export type HeldRun = Selectable<HeldRunsTable>;
 export type NewHeldRun = Insertable<HeldRunsTable>;
 export type HeldRunUpdate = Updateable<HeldRunsTable>;
+/**
+ * One approver's recorded decision on a held element. Multiple rows accumulate
+ * until the hold's `ApprovalRequirement` clauses are all satisfied (approve) or
+ * any single reject lands.
+ */
+export interface HeldRunApprovalsTable {
+    /** UUID primary key */
+    id: Generated<string>;
+    /** FK to held_runs.id (ON DELETE CASCADE) */
+    held_run_id: string;
+    /** The approver's user id (Keycloak sub) */
+    approver_user_id: string;
+    /** 'approve' | 'reject' (engine `ApprovalDecision`) */
+    decision: string;
+    /** Which requirement clauses this decision satisfied (for attribution). */
+    clauses_satisfied: ColumnType<ApproverClause[] | null, ApproverClause[] | string | null | undefined, ApproverClause[] | string | null>;
+    /** When the decision was recorded */
+    created_at: Generated<Date>;
+}
+export type HeldRunApproval = Selectable<HeldRunApprovalsTable>;
+export type NewHeldRunApproval = Insertable<HeldRunApprovalsTable>;
+export type HeldRunApprovalUpdate = Updateable<HeldRunApprovalsTable>;
 /**
  * Secret audit log table
  * Immutable log of secret access and denial events.
@@ -885,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>;
@@ -1192,6 +1237,17 @@ export interface OrgSettingsTable {
      * BIGINT — pg returns a string on select; accept a number on insert/update.
      */
     dispatch_ack_timeout_ms: ColumnType<string | null, number | null | undefined, number | null>;
+    /**
+     * Per-org expiry (seconds) for a held approval element before it is rejected
+     * and its run/job/step fails. NOT NULL, default 86400 (one day). An SDK
+     * `requireApproval` `timeout` overrides this per element.
+     */
+    approval_expiry_seconds: ColumnType<number, number | undefined, number>;
+    /**
+     * Whether the user who triggered a run may also approve its held elements.
+     * NOT NULL, default true. Operators turn it off to enforce four-eyes review.
+     */
+    allow_self_approval: ColumnType<boolean, boolean | undefined, boolean>;
     /** When this setting was created */
     created_at: Generated<Date>;
     /** When this setting was last updated */
@@ -1220,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
@@ -1238,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;
@@ -1246,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;
@@ -1405,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/bundle-writer.d.ts

@@ -6,8 +6,8 @@
  * This is the primary support tool -- operators run debug-bundle and share
  * the ZIP for troubleshooting.
  */
-import archiver from 'archiver';
 import type { DiagnosticDeps } from './types.js';
+export { redactConfig, addLogsToArchive } from '@kici-dev/shared';
 export interface BundleOptions {
     /** Where to write the ZIP. */
     outputPath: string;
@@ -26,11 +26,6 @@ export interface BundleOptions {
     /** URL for recent runs endpoint. */
     recentRunsUrl?: string;
 }
-/**
- * Redact config values using allowlist approach.
- * Only known-safe fields are preserved; everything else becomes "****".
- */
-export declare function redactConfig(obj: unknown, parentKey?: string): unknown;
 /**
  * Create a debug bundle ZIP file.
  *
@@ -43,15 +38,4 @@ export declare function redactConfig(obj: unknown, parentKey?: string): unknown;
  * - logs/summary.json: log statistics
  */
 export declare function createDebugBundle(options: BundleOptions): Promise<string>;
-/**
- * Add log files from logDir to the archive, respecting MAX_LOG_BYTES cap
- * and the logWindow time filter. Matches any `*.log` file in the directory,
- * so the per-instance filename pattern produced by
- * `buildLogFilename()` is picked up without additional configuration.
- *
- * Exported for reuse by the `kici-admin debug-bundle` CLI command, which
- * runs outside the orchestrator process but still needs to include the
- * same log files in its locally-assembled bundle.
- */
-export declare function addLogsToArchive(archive: archiver.Archiver, logDir: string, logWindowHours: number): Promise<void>;
 //# sourceMappingURL=bundle-writer.d.ts.map

package/dist/diagnostics/checks/firecracker-network.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Firecracker host-bridge diagnostic. Emits one row per configured Firecracker
+ * scaler backend: the bridge interface + its gateway addr + its nft table must
+ * all be present, else the scaler cannot spawn microVMs.
+ */
+import type { DiagnosticDeps, DiagnosticResult } from '../types.js';
+import { type BridgeHealth, type FirecrackerBridgeConfig } from '../../firecracker/host-network.js';
+interface CheckOpts {
+    verify?: (cfg: FirecrackerBridgeConfig) => Promise<BridgeHealth>;
+}
+export declare function checkFirecrackerNetwork(deps: DiagnosticDeps, opts?: CheckOpts): Promise<DiagnosticResult[]>;
+export {};
+//# sourceMappingURL=firecracker-network.d.ts.map

package/dist/diagnostics/checks/index.d.ts

@@ -12,7 +12,8 @@ import { checkDiskSpace } from './disk.js';
 import { checkConfigValidity } from './config.js';
 import { checkCertificateExpiry } from './certs.js';
 import { checkScalerProvisioning } from './scaler.js';
+import { checkFirecrackerNetwork } from './firecracker-network.js';
 /** All diagnostic checks in display order. */
 export declare const defaultChecks: DiagnosticCheck[];
-export { checkDbConnectivity, checkWsToPlatform, checkAgentConnectivity, checkDiskSpace, checkConfigValidity, checkCertificateExpiry, checkScalerProvisioning, };
+export { checkDbConnectivity, checkWsToPlatform, checkAgentConnectivity, checkDiskSpace, checkConfigValidity, checkCertificateExpiry, checkScalerProvisioning, checkFirecrackerNetwork, };
 //# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,52 @@
+/**
+ * Recursive fleet subtree assembler.
+ *
+ * Every orchestrator runs this to produce a self-similar subtree ZIP:
+ * local/ + nested agents/<id>.zip + workers/<id>.zip + peers/<id>.zip, plus
+ * fleet-manifest.json recording per-node status. Dead branches are recorded,
+ * never fatal (Promise.allSettled at each level). The loop guard
+ * (includeCoordinatorMesh) is true only on the root call; every downstream peer
+ * request sets it false so the coordinator mesh never echoes.
+ */
+import { z } from 'zod';
+/** Per-node collection outcome recorded in the fleet manifest. */
+export declare const FleetNodeStatus: z.ZodEnum<{
+    error: "error";
+    ok: "ok";
+    unreachable: "unreachable";
+    timeout: "timeout";
+}>;
+export type FleetNodeStatus = z.infer<typeof FleetNodeStatus>;
+export interface FleetCollectorDeps {
+    /** This orchestrator's instanceId (the manifest owner). */
+    instanceId: string;
+    /** Build this node's own debug bundle as a Buffer (createDebugBundle output). */
+    buildLocalBundle: () => Promise<Buffer>;
+    /** List this node's directly-connected agents. */
+    listAgents: () => {
+        agentId: string;
+    }[];
+    /** Request a connected agent's mini-bundle over the agent WS channel. */
+    requestAgentBundle: (agentId: string) => Promise<Buffer>;
+    /** List this node's downstream peers (coordinator-mesh peers + its workers). */
+    listPeers: () => {
+        instanceId: string;
+        role: 'coordinator' | 'worker';
+        kind: 'peer' | 'worker';
+    }[];
+    /** Request a peer's subtree bundle over the peer WS channel (loop-guarded false). */
+    requestPeerSubtree: (instanceId: string, includeCoordinatorMesh: boolean) => Promise<Buffer>;
+}
+export interface FleetCollectOptions {
+    logWindowHours: number;
+    selection: {
+        all: boolean;
+        agentIds: string[];
+        workerInstanceIds: string[];
+    };
+    /** Loop guard. True only on the root call; downstream requests force false. */
+    includeCoordinatorMesh: boolean;
+    timeoutMs: number;
+}
+export declare function collectFleetSubtree(opts: FleetCollectOptions, deps: FleetCollectorDeps): Promise<Buffer>;
+//# sourceMappingURL=fleet-collector.d.ts.map

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

@@ -0,0 +1,8 @@
+/**
+ * Shared constants for fleet log collection.
+ */
+/** Default per-node deadline for a fleet bundle request (overridable via --fleet-timeout). */
+export declare const FLEET_NODE_TIMEOUT_MS = 60000;
+/** Per-node cap on raw log bytes an agent includes in its mini-bundle (50 MiB). */
+export declare const FLEET_MAX_LOG_BYTES: number;
+//# sourceMappingURL=fleet-constants.d.ts.map