@kici-dev/orchestrator 0.6.1 → 0.7.0

package/dist/oidc/id-token-claims.d.ts

@@ -8,7 +8,7 @@
  * differs only in the local sentinel issuer (`kici-local`) and the org anchor
  * (`__default__`, the plane's default org).
  */
-import { AttestationOrigin, SourceOrigin } from '@kici-dev/engine';
+import { AttestationOrigin, SourceOrigin, type EventClaims } from '@kici-dev/engine';
 /** The subset of an execution_runs row the claims need. */
 export interface RunClaimSource {
     run_id: string;
@@ -20,6 +20,24 @@ export interface RunClaimSource {
     provider: string | null;
     /** True when the run executed an uploaded local working tree (`kici run remote`). */
     local_working_tree: boolean;
+    /** Normalized event that started the run (`push`, `pull_request:opened`, …). */
+    trigger_event?: string | null;
+    /**
+     * The event the SUBJECT is derived from, when that is not `trigger_event`.
+     * A re-run carries the original run's event here. NULL means "use
+     * `trigger_event`". Read only by `buildIdTokenSubject`.
+     */
+    subject_trigger_event?: string | null;
+    /** Pull-request HEAD branch. */
+    head_ref?: string | null;
+    /** `owner/repo` of the pull-request HEAD. */
+    head_repository?: string | null;
+    /** True for a fork pull request; NULL when the run resolved no answer. */
+    is_fork?: boolean | null;
+    /** Resolved trust tier for the triggering actor. */
+    trust_tier?: string | null;
+    /** Provider login of the triggering actor. */
+    trigger_actor_username?: string | null;
 }
 /** The subset of an execution_jobs row the claims need. */
 export interface JobClaimSource {
@@ -43,8 +61,21 @@ export interface BuildClaimsOpts {
         statementHash: string;
         origin: 'deferred' | 'offline-backfill';
     };
+    /**
+     * Restore the pre-split pull-request `sub` — the branch-shaped form that
+     * collides with a push to the same base branch. An escape hatch for an
+     * operator whose cloud trust policy breaks mid-migration, set by
+     * `KICI_OIDC_LEGACY_PR_SUB`.
+     *
+     * @deprecated Removed at v1.0.0. Move the policy to `repo:<repo>:pull_request`.
+     */
+    legacyPullRequestSubject?: boolean;
 }
-export interface IdTokenClaims {
+/**
+ * Extends {@link EventClaims}, so every token carries the event-context claims
+ * a cloud trust policy needs to tell a fork pull request from a push.
+ */
+export interface IdTokenClaims extends EventClaims {
     iss: string;
     sub: string;
     aud: string;

package/dist/oidc/oidc-mint-registration.d.ts

@@ -56,6 +56,12 @@ export interface OidcMintRegistrationInput {
     };
     db: Kysely<Database>;
     orchestratorId: string;
+    /**
+     * `KICI_OIDC_LEGACY_PR_SUB` — restore the pre-split pull-request `sub`.
+     *
+     * @deprecated Removed at v1.0.0.
+     */
+    legacyPullRequestSubject?: boolean;
     /**
      * Test-only fault-injection predicate forwarded to the relay mint handler,
      * supplied only by the build-time test double. Only ever defers — the

package/dist/oidc/orchestrator-mint.d.ts

@@ -36,6 +36,14 @@ export interface OrchestratorMintDeps {
     ttlSeconds?: number;
     /** Injectable clock (seconds). Defaults to wall-clock. */
     nowSeconds?: () => number;
+    /**
+     * Restore the pre-split pull-request `sub`, from `KICI_OIDC_LEGACY_PR_SUB`.
+     * An escape hatch for an operator whose cloud trust policy breaks mid-
+     * migration; leaves the collision with a same-branch push in place.
+     *
+     * @deprecated Removed at v1.0.0.
+     */
+    legacyPullRequestSubject?: boolean;
 }
 export interface OrchestratorMintInput {
     runId: string;

package/dist/oidc/reconcile-signing-key.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Boot reconcile for the orchestrator's provenance signing key. Ensures exactly
+ * one `active` key exists and returns a live `Signer` bound to it.
+ *
+ *  - `db` custody: the private key is a random keypair generated + persisted
+ *    (master-key-wrapped) in the DB. Generation is LEADER-GATED so an HA cluster
+ *    never races two active keys; every node then loads the one active row. A
+ *    non-leader that finds no active row yet returns null this tick and is
+ *    retried on the next leadership/boot cycle.
+ *  - `aws-kms` / `command` custody: the key lives outside KiCI, so every node
+ *    resolves the SAME kid and `upsertActive` is idempotent across the fleet.
+ */
+import type { JWK } from 'jose';
 import { type OrchestratorSignerConfig } from './orchestrator-signer-factory.js';
 import type { Signer } from './signer.js';
 import type { OrchestratorSigningKeyRepo } from '../db/repos/signing-keys-repo.js';
@@ -7,6 +20,30 @@ export interface ReconcileSigningKeyDeps {
     isLeader: () => boolean;
     /** The orchestrator master key (`KICI_SECRET_KEY`), for `db` custody wrapping. */
     secretKey: string | undefined;
+    /**
+     * The previous master key (`KICI_SECRET_KEY_OLD`), during a rotation grace
+     * window. The signing key is master-key wrapped, so a rotation that has not
+     * yet swept `orchestrator_signing_keys` leaves the row sealed under the old
+     * key — without this fallback the boot path throws and provenance signing is
+     * dead until the old key is restored.
+     */
+    oldSecretKey?: string | undefined;
+    /**
+     * Re-seal a row that opened only under the OLD master key, back under the
+     * current one. Optional: when unset the row is loaded and left as it is, so
+     * signing works but stays stranded. Best-effort — a failure is warned and
+     * never blocks the boot.
+     *
+     * This is the recovery path for a deployment stranded by a rotation that ran
+     * before `orchestrator_signing_keys` was part of the sweep: restore the old
+     * key once, restart, and the row moves to the current key on its own.
+     */
+    selfHeal?: (row: {
+        kid: string;
+        key_version: number;
+    }, privateJwk: JWK) => Promise<void>;
+    /** Structured warn sink for the self-heal notice. */
+    logWarn?: (message: string, meta: Record<string, unknown>) => void;
     /** Called once when a NEW kid is first activated (audit log, system actor). */
     audit: (info: {
         kid: string;

package/dist/orchestrator-core.d.ts

@@ -47,7 +47,7 @@ import { LogWriter } from './reporting/log-writer.js';
 import { type NormalizedLogChunk } from './reporting/log-chunk-sink.js';
 import { PeerRegistry, PeerClient, createPeerHandler, RaftNode, OrphanRecovery, RunCoordinator, PlanHeadroomStore } from './cluster/index.js';
 import { SourceStore, SourceManager } from './sources/index.js';
-import { PgSecretStore, AuditLogger, SecretResolver } from './secrets/index.js';
+import { type ResolvedMasterKeys, PgSecretStore, AuditLogger, SecretResolver } from './secrets/index.js';
 import type { SecretStore } from '@kici-dev/engine';
 import type { AdminRouteDeps } from './routes/admin.js';
 import { AgentTokenStore } from './agent/token-store.js';
@@ -56,7 +56,7 @@ import { EventStore } from './events/event-store.js';
 import { EventRouter, type EventMatchContext } from './events/event-router.js';
 import { EventEmitter } from './events/event-emitter.js';
 import { TrustStore } from './events/trust-store.js';
-import type { OrchestratorFaultInjection } from './testing/fault-injection.js';
+import type { OrchestratorFaultInjection } from './fault-injection-types.js';
 import { GenericSourceManager } from './webhook/generic-sources.js';
 import { GenericSourcesChangeListener } from './webhook/generic-sources-listener.js';
 import { DashboardWritePolicyChangeListener } from './policy/dashboard-write-policy-listener.js';
@@ -392,7 +392,7 @@ export declare function buildMatrixOutputsEnvelope(baseName: string, children: A
  * 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<{
+export declare function mergeUpstreamOutputs(db: Kysely<Database>, runId: string, jobName: string, needs: unknown, dispatchSecrets: Record<string, string> | undefined, masterKeys: ResolvedMasterKeys | null): Promise<{
     mergedSecrets: Record<string, string> | undefined;
     upstreamJobOutputs: Record<string, Record<string, unknown>> | undefined;
     upstreamJobStatuses: Record<string, ExecutionJobStatus> | undefined;
@@ -434,5 +434,11 @@ export declare function bootstrapOrchestrator(config: AppConfig, hooks: Orchestr
      * drive the seams directly.
      */
     faultInjection?: OrchestratorFaultInjection;
+    /**
+     * This build's version, recorded on the coordinator heartbeat row. Read by
+     * an operator during a rolling upgrade to see which coordinators have
+     * already moved. Undefined leaves the column NULL.
+     */
+    orchestratorVersion?: string;
 }): Promise<void>;
 //# sourceMappingURL=orchestrator-core.d.ts.map

package/dist/pipeline/decorating-secret-resolver.d.ts

@@ -23,7 +23,7 @@ export declare class DecoratingSecretResolver implements SecretResolverApi {
     private readonly cli;
     constructor(base: SecretResolverApi, cli: CliSecrets);
     resolveForJob(orgId: string, contextName: string, hostCtx?: HostFacts): Promise<Record<string, string>>;
-    resolveNamed(orgId: string, scope: string, key: string, opts?: {
+    resolveNamedInternal(orgId: string, scope: string, key: string, opts?: {
         store?: string;
         runId?: string;
         jobId?: string;

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

@@ -14,8 +14,9 @@
  * results through the pipeline.
  */
 import { ExecutionJobStatus, InitFailureCategory, CacheRefScope, HoldScope, TriggerSource } from '@kici-dev/engine';
-import type { LabelMatcher, LockWorkflow, LockJob, ApprovalRequirement, HostTargetSelector, SimulatedEvent, WorkflowDecision, MaterializedJob, ResolvedHostAgent, HostFacts } from '@kici-dev/engine';
+import type { LabelMatcher, LockWorkflow, LockJob, ApprovalRequirement, HostTargetSelector, SimulatedEvent, WorkflowDecision, MaterializedJob, ResolvedHostAgent, UpstreamSnapshot, HostFacts } from '@kici-dev/engine';
 import { type HostRosterStore } from '../agent/host-roster.js';
+import { NEEDS_PENDING_JOB_ID_PREFIX } from '../db/synthetic-job-ids.js';
 import { gatherInvokeResults } from '../orchestrator-core.js';
 import type { WebhookInfo } from '../webhook/handler.js';
 import type { ProviderBundle } from '../provider-registry.js';
@@ -24,6 +25,7 @@ import type { QueuedJobInput } from '../queue/job-queue.js';
 import type { TrustResolution } from '../security/trust-resolver.js';
 import type { TrustPolicyOutcome } from '../security/trust-policy-gate.js';
 import type { CreateHeldRunData } from '../contexts/held-runs.js';
+import { type NpmRegistrySpec } from './install-secrets-resolver.js';
 import { type ProcessingDeps } from './processor.js';
 /**
  * Trusted refs (write+ contributor, default-branch) get the org-shared cache
@@ -82,26 +84,34 @@ export interface WorkflowDispatchContext {
     fullLockFile: {
         workflows: readonly LockWorkflow[];
         lockfileHash?: string;
+        /** In-repo `workspace:` sibling closure digest; part of the dep pointer key. */
+        siblingsDigest?: string;
         source: {
             file: string;
         };
     };
     resolvedOrgId: string;
     /**
-     * Siblings admitted against a context concurrency limit during THIS dispatch
-     * pass, keyed by {@link concurrencyAdmissionKey}.
+     * The NAMES of the jobs this dispatch pass has admitted against a context
+     * concurrency limit, keyed by {@link concurrencyAdmissionKey}.
      *
-     * The gate's running count counts jobs whose status is already `running`, so
-     * it cannot see anything this pass has only just admitted. Without this tally
-     * every child of a fan-out is evaluated against that one blind value and all
-     * N are admitted against a single slot.
+     * The database count cannot see a job this pass has only just admitted, so
+     * without this tally every child of a fan-out is evaluated against that one
+     * blind value and all N are admitted against a single slot.
+     *
+     * Names rather than a counter, because the two terms have to be DISJOINT: the
+     * count query excludes exactly the names held here (see
+     * {@link countOccupyingJobs}), so a job whose row has already landed
+     * contributes its tally entry and nothing else. A counter cannot express that
+     * exclusion, and summing it with a count that already sees the row is how the
+     * deferred-init path double-counts a sibling and spuriously holds a job.
      *
      * Created lazily on first use and dropped with the ctx. It is per-pass state,
-     * never persisted and never shared between passes; two concurrent passes
-     * still race, which is accepted — this is a throughput control, not an
-     * isolation boundary.
+     * never persisted and never shared between passes; two actors arriving in the
+     * same millisecond still race between the count and the insert, which is
+     * accepted — this is a throughput control, not an isolation boundary.
      */
-    concurrencyAdmissions?: Map<string, number>;
+    concurrencyAdmissions?: Map<string, Set<string>>;
     workflow: LockWorkflow;
     decision: WorkflowDecision;
     runId: string;
@@ -373,6 +383,8 @@ interface DispatchSetup {
 interface BuildPrepResult {
     sourceTarUrl: string | undefined;
     sourceTarHash: string | undefined;
+    /** SHA-256 of the source tarball's own bytes; the agent verifies against it. */
+    sourceTarDigest: string | undefined;
     depsUrl: string | undefined;
     depsHash: string | undefined;
     contentHash: string | undefined;
@@ -482,8 +494,11 @@ interface JobEnvEvalResult {
  * keys on it, so it is load-bearing rather than cosmetic — which is what makes
  * it a sound way to recover the gated set without threading a parallel list
  * through both the single-orchestrator and cluster dispatch paths.
+ *
+ * Re-exported from `db/synthetic-job-ids.ts`, which owns it so the concurrency
+ * sweep in `contexts/` can exclude these rows without importing this module.
  */
-export declare const NEEDS_PENDING_JOB_ID_PREFIX = "needs-pending-";
+export { NEEDS_PENDING_JOB_ID_PREFIX };
 interface RejectedJob {
     jobId: string;
     jobName: string;
@@ -510,7 +525,7 @@ interface RejectedJob {
  * cloud-hosted one-shot agent, an air-gapped runner) could not run the job at
  * all. The `__build__` job already carries `buildSourceNeeded` /
  * `buildDepsNeeded` separately and the agent already honors both, so a
- * deps-only build was implemented and simply unreachable.
+ * deps-only build was implemented and unreachable.
  *
  * A hash is required alongside its miss: with no hash there is no cache key to
  * write, so building would produce an artifact nothing could ever look up.
@@ -563,6 +578,16 @@ interface JobRoutingSelectors {
     runsOnPatterns: LabelMatcher[];
     excludeLabels: string[];
     excludePatterns: LabelMatcher[];
+    /**
+     * The `runsOn` exact values exactly as the lock file spells them, before the
+     * canonical fold `partitionMatchers` applies.
+     *
+     * Only {@link resolveRosterAgentPin} reads this. A bare agent id in `runsOn`
+     * is the documented inventory fan-out pattern (`runsOn: [h.agentId]`), and an
+     * agent id is not a label: `host_roster.agent_id` is case-sensitive, so the
+     * folded form misses every host whose id carries a capital.
+     */
+    runsOnExactRaw: string[];
 }
 /**
  * Partition a lock job's runsOn / excludeLabels matchers into exact labels (SQL
@@ -606,9 +631,15 @@ export declare function requiredRuntimeLabelsFor(container: unknown): string[];
  * cross-cluster reroute) — exact parity with how `runsOnAll` children pin. Any
  * other shape (multi-label, a regex pattern, a non-roster label, or no roster
  * store) returns null and the caller keeps normal label routing.
+ *
+ * `runsOnExact` takes the values the lock file spells, NOT the canonical labels
+ * every other routing path uses: this looks the value up as an agent id, and
+ * agent ids are case-sensitive. Handing it folded labels strands every host
+ * whose id carries a capital on the normal label path, where a bare agent id
+ * matches nothing.
  */
 export declare function resolveRosterAgentPin(args: {
-    runsOnLabels: string[];
+    runsOnExact: string[];
     runsOnPatterns: LabelMatcher[];
     hostRosterStore: HostRosterStore | undefined;
 }): Promise<{
@@ -865,6 +896,12 @@ export interface GeneratedJobConfig {
     connectedInstanceId?: string | null;
     /** The matrix combination for this child; absent for non-matrix generated jobs. */
     matrixValues?: Record<string, unknown>;
+    /**
+     * The `gitCredentials` map the generator's LOCK entry declared, inherited by
+     * this child. Persisted to `execution_jobs.git_credentials` at every dispatch
+     * site below, which is what the credential relay authorizes a request against.
+     */
+    gitCredentials?: Readonly<Record<string, Readonly<Record<string, string>>>>;
 }
 /**
  * Split generated configs into pinned (host-pin dispatch) and unpinned (normal
@@ -876,6 +913,20 @@ export declare function partitionGeneratedConfigsByPin(configs: readonly Generat
     pinnedConfigs: GeneratedJobConfig[];
     unpinnedConfigs: GeneratedJobConfig[];
 };
+export declare function resolveGeneratedJobConfigs(args: {
+    ctx: WorkflowDispatchContext;
+    workflow: LockWorkflow;
+    fullLockFile: WorkflowDispatchContext['fullLockFile'];
+    resolvedSecrets: Record<string, string> | undefined;
+    resolvedNamespacedSecrets: Record<string, Record<string, string>> | undefined;
+    runPublicKeyBase64: string | undefined;
+    npmRegistries: NpmRegistrySpec[] | undefined;
+    installEnvSecrets: Record<string, string> | undefined;
+    generatedJobs: LockJob[];
+    dynamicEntry: BuildPrepResult['dynamicEntries'][number];
+    /** Frozen upstream snapshot threaded into each generated job's dynamicSource for re-eval. */
+    upstreamSnapshot?: UpstreamSnapshot;
+}): Promise<GeneratedJobConfig[]>;
 /**
  * Recompute the needs gate for `jobNames` and act on whatever became ready:
  * open the gate for a satisfied job, terminalize a job an upstream's status

package/dist/pipeline/manual-schedule.d.ts

@@ -49,6 +49,7 @@ export declare function buildManualJobConfig(workflow: LockWorkflow, mat: Materi
         runOn: ("cancelled" | "cancelling" | "drift_dropped" | "failed" | "pending" | "queued" | "recovering" | "running" | "skipped" | "success" | "timed_out_stale" | "unroutable")[];
     })[];
     rules: readonly import("@kici-dev/engine").LockRule[] | undefined;
+    gitCredentials?: Readonly<Record<string, Readonly<Record<string, string>>>> | undefined;
     dispatchInputs?: Record<string, unknown> | undefined;
     contentHash?: string | undefined;
     resolvedHashFiles?: string[] | undefined;

package/dist/pipeline/process-webhook.d.ts

@@ -22,7 +22,7 @@ import type { OrchestratorMode } from '@kici-dev/engine';
 import type { WebhookInfo } from '../webhook/handler.js';
 import type { ProviderBundle } from '../provider-registry.js';
 import { type TrustResolution } from '../security/trust-resolver.js';
-import { type TrustPolicyOutcome } from '../security/trust-policy-gate.js';
+import { type ForkSwitchContext, type TrustPolicyOutcome } from '../security/trust-policy-gate.js';
 import { type WorkflowModification } from '../security/workflow-diff.js';
 import type { IdentityLink, PermissionLevel } from '../security/identity-link.js';
 import { type ProcessingDeps } from './processor.js';
@@ -143,6 +143,20 @@ export declare function applyWorkflowModificationsAndSecurityHold(args: {
     ref: string;
     credentials: Record<string, unknown>;
 }): SecurityState;
+/**
+ * A trust-policy verdict plus the fork switch it was decided under.
+ *
+ * The first arm is the short-circuit: a non-PR event, or a provider with no
+ * fork model, decides `pass` before any policy is read, so there is no switch
+ * to report. Every other verdict comes from an actual policy and carries it —
+ * which is what lets the drop site read `forkSwitch` without a fallback that
+ * would have to invent a source it never observed.
+ */
+export type SecurityPolicyDecision = {
+    action: 'pass';
+} | (TrustPolicyOutcome & {
+    forkSwitch: ForkSwitchContext;
+});
 /**
  * Evaluate the org trust policy for a PR event.
  *
@@ -157,6 +171,10 @@ export declare function applyWorkflowModificationsAndSecurityHold(args: {
  * The policy read has two distinct failure shapes, and they get distinct
  * answers: no stored row is the unconfigured default (`FAIL_CLOSED_POLICY`),
  * while a read that THREW gets `READ_FAILURE_POLICY` — see there for why.
+ *
+ * The verdict carries the fork switch it was decided under, so the drop site
+ * can explain itself. It is absent on the two short-circuit `pass` arms below,
+ * which return before any policy is read.
  */
 export declare function evaluateSecurityPolicy(args: {
     deps: ProcessingDeps;
@@ -166,7 +184,7 @@ export declare function evaluateSecurityPolicy(args: {
     mode: OrchestratorMode;
     trustResolution: TrustResolution | undefined;
     isForkPR: boolean;
-}): Promise<TrustPolicyOutcome>;
+}): Promise<SecurityPolicyDecision>;
 /**
  * Phase J — After per-repo workflows are dispatched, query the global index
  * for workflows authored in OTHER repos that target this event type via

package/dist/pipeline/route-or-dispatch-jobs.d.ts

@@ -34,6 +34,13 @@ export interface DispatchedJobEntry {
     jobKind?: JobKind;
     /** For a gate job, its wall-clock timeout in ms (orchestrator-swept). */
     timeoutMs?: number;
+    /**
+     * The `gitCredentials` map this job's lock entry declared, verbatim.
+     * Persisted to `execution_jobs.git_credentials`, which the credential relay
+     * authorizes a workflow-supplied ref against. Dropping it here would refuse
+     * every declared credential on a job this path registered.
+     */
+    gitCredentials?: Readonly<Record<string, Readonly<Record<string, string>>>>;
 }
 export interface RejectedJobEntry {
     jobId: string;

package/dist/pipeline/run-event-context.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Resolve the pull-request head context an `execution_runs` row records.
+ *
+ * `execution_runs.ref` is the branch a run PRESENTS — the BASE branch for a
+ * pull request — so it says which branch a run targeted and nothing about where
+ * the code came from. These three fields are the missing half, and the OIDC
+ * mint reads them: without them a fork pull request and a trusted push to the
+ * same base branch mint an identical identity.
+ */
+import { type SimulatedEvent } from '@kici-dev/engine';
+export interface RunEventContext {
+    headRef: string | null;
+    headRepository: string | null;
+    isFork: boolean | null;
+}
+/**
+ * Derive the head context from a normalized event.
+ *
+ * `isFork` is resolved from the event TYPE, not from the presence of the
+ * optional flag. A push, tag or schedule has no fork dimension, so `false` is
+ * its true resolved value — not a stand-in. Leaving those unresolved would make
+ * every `is_fork = 'false'` cloud trust policy reject legitimate pushes, and the
+ * customer's fix for that (accepting `'unresolved'` too) would re-open the hole
+ * the claim exists to close.
+ *
+ * NULL survives for exactly one case: a PR-family event whose payload carries
+ * no head repository, so the fork question genuinely has no answer. A lost
+ * write leaves all three NULL, which every claim renders as unresolved and a
+ * policy that pins them therefore fails closed.
+ *
+ * The head repository is what decides that case, NOT the presence of the
+ * `isForkPR` flag. Every normalizer derives that flag as `head !== base`, which
+ * collapses to `false` when the payload names no head repository — a deleted
+ * fork, or a trimmed payload. Reading the flag alone would therefore publish
+ * `is_fork = 'false'` for a pull request nobody resolved, which is the fail-OPEN
+ * direction this claim exists to remove.
+ */
+export declare function resolveRunEventContext(event: Pick<SimulatedEvent, 'type' | 'sourceBranch' | 'headRepo' | 'isForkPR'>): RunEventContext;
+//# sourceMappingURL=run-event-context.d.ts.map

package/dist/policy/dashboard-write-policy-listener.d.ts

@@ -47,7 +47,7 @@ export interface DashboardWritePolicyChangeListenerOptions {
 }
 export declare class DashboardWritePolicyChangeListener {
     private readonly opts;
-    private client;
+    private listener;
     private readonly pending;
     private debounceTimer;
     private readonly debounceMs;

package/dist/policy/dashboard-write-policy.d.ts

@@ -22,7 +22,7 @@ import { EventEmitter } from 'node:events';
 import { type Kysely } from 'kysely';
 import { DashboardWriteOperation, type DashboardWritePolicyMap, type DashboardWritePolicyState } from '@kici-dev/engine/protocol/dashboard-write-operations';
 import type { Database } from '../db/types.js';
-import type { ActorPrincipal } from '@kici-dev/engine';
+import { type ActorPrincipal, type OrchestratorMode } from '@kici-dev/engine';
 /**
  * Postgres `LISTEN/NOTIFY` channel carrying policy changes across the
  * cluster. The payload is the `customer_id` alone — every coordinator
@@ -54,6 +54,18 @@ export declare class DashboardWritePolicyDisabledError extends Error {
     readonly code: 'operation_disabled';
     constructor(operation: DashboardWriteOperation, cliEquivalent: string);
 }
+/**
+ * Error thrown by `setDashboardWritePolicy` when a write would leave a context
+ * or reviewer hold with no surface that can answer it. Translated into a 409 by
+ * the admin route.
+ */
+export declare class HeldRunLockoutRefusedError extends Error {
+    readonly operations: DashboardWriteOperation[];
+    readonly code: 'held_run_lockout_refused';
+    constructor(operations: DashboardWriteOperation[]);
+}
+/** Say which operations were refused, and why there is no fallback for them. */
+export declare function heldRunLockoutMessage(operations: readonly DashboardWriteOperation[]): string;
 /**
  * Structured response envelope sent back to Platform when a mutating
  * dashboard.* handler is rejected by the policy gate. Mirrors the
@@ -104,9 +116,16 @@ export declare function assertDashboardWriteAllowed(db: Kysely<Database>, custom
  *
  * Emits `'changed'` on `dashboardWritePolicyEvents` with the new map
  * so the WS publisher can rebroadcast capabilities.
+ *
+ * Throws {@link HeldRunLockoutRefusedError} when the write would disable a
+ * held-run operation on a Platform-attached orchestrator, where no other surface
+ * can answer a hold. The check lives here rather than in the admin route so a
+ * caller hitting the API directly is refused too.
  */
 export declare function setDashboardWritePolicy(db: Kysely<Database>, customerId: string, updates: DashboardWritePolicyMap, options: {
     actor: ActorPrincipal;
+    /** This orchestrator's mode; decides whether a held-run disable is coherent. */
+    mode: OrchestratorMode;
     onChange?: (event: PolicyChangeEvent) => Promise<void>;
 }): Promise<DashboardWritePolicyMap>;
 /**
@@ -128,7 +147,34 @@ export interface PolicyChangeEvent {
  */
 export declare function resetDashboardWritePolicy(db: Kysely<Database>, customerId: string, options: {
     actor: ActorPrincipal;
+    mode: OrchestratorMode;
     onChange?: (event: PolicyChangeEvent) => Promise<void>;
 }): Promise<DashboardWritePolicyMap>;
+/**
+ * Report every org whose stored policy already leaves its context and reviewer
+ * holds unanswerable.
+ *
+ * The refusal above only guards FUTURE writes, and the operator hardening
+ * postures documented before it existed recommended exactly this disable — so a
+ * deployment that followed them is locked out right now and would learn nothing
+ * from a check it never trips.
+ *
+ * Deliberately read-only. Silently re-enabling a write an operator disabled on
+ * purpose is a worse failure than the one being reported: the operator chose
+ * that posture, and only they can decide whether to keep the lockout, re-enable
+ * the operation, or move the orchestrator to independent mode.
+ */
+export declare function findHeldRunLockouts(db: Kysely<Database>, mode: OrchestratorMode): Promise<Array<{
+    customerId: string;
+    operations: DashboardWriteOperation[];
+}>>;
+/**
+ * Log one warning per org already in that state, at boot.
+ *
+ * Swallows its own failure: a policy read that cannot answer must not stop an
+ * orchestrator from starting, and the condition it reports is a standing one
+ * that the next boot reports again.
+ */
+export declare function warnOnHeldRunLockouts(db: Kysely<Database>, mode: OrchestratorMode): Promise<void>;
 export { resolveFullPolicyView } from '@kici-dev/engine/protocol/dashboard-write-operations';
 //# sourceMappingURL=dashboard-write-policy.d.ts.map

package/dist/provenance/dispatch-context.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The canonical build context the orchestrator sends with a job, so the agent
+ * can freeze a provenance statement that says what a live mint would have said.
+ *
+ * A deferred attestation is signed BEFORE its identity token exists, so the
+ * agent used to build the frozen statement from facts it held locally — and
+ * those are not the facts the mint reads:
+ *
+ *   - the job's checkout `ref` is the PR HEAD branch, while the token's `ref`
+ *     claim is `execution_runs.ref`, the BASE branch;
+ *   - `request.workflowRef` is the git ref used to CLONE a global workflow's
+ *     repository, while the token's `workflow_ref` claim is
+ *     `<workflow_name>@<sha>`. Those two are never equal;
+ *   - `provenanceIssuer` is declared and read but written by no dispatch path,
+ *     so every frozen statement recorded `builder.id` as `/orchestrator/unknown`.
+ *
+ * So a field-by-field cross-check would have failed on every legitimate
+ * deferred attestation — which is exactly why the verifier's deferred branch
+ * was written as a hash equality instead. Sending the mint's own view of the
+ * run makes the cross-check meaningful, and only then can it be switched on.
+ */
+import type { Kysely } from 'kysely';
+import { type ProvenanceContext } from '@kici-dev/engine';
+import type { Database } from '../db/types.js';
+/**
+ * Load the provenance context for a (run, job) from the same rows and the same
+ * derivations `buildIdTokenClaims` uses.
+ *
+ * Returns undefined only when the run row is absent. In particular this does
+ * NOT gate on a configured provenance issuer: the cross-check reads
+ * `repository` / `ref` / `sha` / `workflowRef` / `runId` / `jobId`, none of
+ * which depends on who signs the token. Only the statement's `builder.id`
+ * needs an issuer, and an unset one reproduces the `/orchestrator/unknown`
+ * builder the local guess has always recorded.
+ *
+ * Gating on the issuer here dropped the context for every orchestrator still
+ * on the deprecated Platform-relay mint, so its agent fell back to the local
+ * guess — `repository: 'unknown/unknown'` for a `file://` clone, and a bare
+ * workflow name where the claim is `<name>@<sha>` — and the capture check
+ * then refused every one of its deferred attestations.
+ */
+export declare function loadProvenanceContext(db: Kysely<Database>, runId: string, jobId: string, opts: {
+    issuer: string | undefined;
+    orchestratorId: string;
+}): Promise<ProvenanceContext | undefined>;
+//# sourceMappingURL=dispatch-context.d.ts.map

package/dist/provenance/verify-deferred-capture.d.ts

@@ -0,0 +1,39 @@
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import { DeferredAttestationRejectReason } from '../metrics/prometheus.js';
+/** What the capture handler hands over, before anything is persisted. */
+export interface DeferredCaptureRecord {
+    runId: string;
+    jobId: string;
+    subjectDigest: string;
+    statementHash: string;
+    dsseEnvelope: unknown;
+}
+/**
+ * Accepted, with the RECOMPUTED statement hash — never the agent-supplied one,
+ * even when they agree. The later mint binds the token to this value.
+ */
+export type DeferredCaptureVerdict = {
+    ok: true;
+    statementHash: string;
+} | {
+    ok: false;
+    reason: DeferredAttestationRejectReason;
+    detail: string;
+};
+/**
+ * Check a deferred capture against the orchestrator's own rows, fail closed.
+ *
+ * A rejection is a DROP: the job stays green and has no attestation.
+ * That is a degradation, whereas storing an unchecked statement re-introduces
+ * the forgery primitive — every gate that lets one through is the hole again.
+ * An agent too old to receive `provenanceContext` freezes the legacy statement
+ * shape and is dropped for the same reason, with the mismatched field named so
+ * the operator can see the upgrade is what fixes it.
+ */
+export declare function checkDeferredCapture(deps: {
+    db: Kysely<Database>;
+    record: DeferredCaptureRecord;
+    orchestratorId: string;
+}): Promise<DeferredCaptureVerdict>;
+//# sourceMappingURL=verify-deferred-capture.d.ts.map

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

@@ -15,6 +15,15 @@ export interface GitHubAppConfig {
     /** GitHub App private key (PEM format) */
     privateKey: string;
 }
+/**
+ * Create an Octokit instance authenticated as the GitHub App itself (a JWT
+ * signed with the App private key), not as one of its installations.
+ *
+ * App-level endpoints — `GET /app`, `GET /app/installations`, and the webhook
+ * delivery endpoints under `/app/hook/deliveries` — accept only this
+ * credential. Installation tokens are rejected there.
+ */
+export declare function createAppOctokit(config: GitHubAppConfig): Octokit;
 /**
  * Credentials for GitHub operations requiring installation-level access.
  */