@kici-dev/orchestrator 0.4.0 → 0.6.0

package/dist/pipeline/security-hold-check.d.ts

@@ -0,0 +1,217 @@
+import { type CheckStatus, type CheckStatusPoster } from '@kici-dev/engine';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+/** Resolve the check poster of the provider bundle a routing key is served by. */
+export type ResolveCheckStatusPoster = (routingKey: string) => CheckStatusPoster | undefined;
+/**
+ * The `held_runs` columns this module reads. A full `HeldRun` row satisfies it,
+ * so every caller passes the row it already loaded rather than a projection.
+ */
+export interface SecurityCheckHold {
+    id: string;
+    org_id: string;
+    run_id: string;
+    job_id: string;
+    hold_scope: string;
+    hold_type: string;
+    approval_requirement: unknown;
+    /**
+     * Whether the pending post reached the provider. Required rather than
+     * optional so a query that projects columns by name cannot omit it and fall
+     * back to the shape derivation without the compiler saying so.
+     */
+    posted_pending_check: boolean | null;
+}
+/** How a hold ended, which decides the conclusion, title and summary. */
+export declare enum HoldOutcome {
+    /** Released to run — an approver satisfied it. */
+    Approved = "approved",
+    /** Refused by an approver. */
+    Rejected = "rejected",
+    /** Nobody answered inside the approval window. */
+    Expired = "expired"
+}
+/** Why {@link settleSecurityHoldCheck} did or did not write the check. */
+export declare enum SecurityCheckSettlement {
+    /** A terminal status was written. */
+    Posted = "posted",
+    /** This hold posted no pending check, so it has none to terminalize. */
+    NotOwned = "not-owned",
+    /** The caller already wrote this commit's check earlier in the same pass. */
+    AlreadySettled = "already-settled",
+    /** Another pending hold on the same commit still owns the check. */
+    Contended = "contended",
+    /** The hold's run row is gone, so the commit cannot be named. */
+    NoCommit = "no-commit",
+    /** No provider bundle serves the run's routing key any more. */
+    NoPoster = "no-poster",
+    /**
+     * The settlement could not complete — the provider refused the write, or the
+     * hold row did not carry the columns the ownership predicate reads.
+     */
+    Failed = "failed"
+}
+export interface SettleSecurityCheckResult {
+    outcome: SecurityCheckSettlement;
+    /** Whether a terminal status actually reached the provider. */
+    posted: boolean;
+    /** `owner/repo@sha`, once the hold's commit resolved. */
+    commit?: string;
+}
+/**
+ * Whether this hold put a pending `KiCI Security` check on its commit, and so
+ * has one to terminalize when it ends.
+ *
+ * `posted_pending_check` is the answer whenever the row carries one: it is
+ * written `true` only after the provider accepted the post, so it records what
+ * HAPPENED. Everything below records what the code INTENDED, which is a
+ * different question and answers the wrong way twice — a post the provider
+ * refused, and a hold reached with no check poster in `ctx.bundle`, both leave
+ * a shape that says "posted" and a commit that has nothing. Terminalizing then
+ * CREATES the check run, so the mirror of the stuck-check leak is a fabricated
+ * failing check on a pull request.
+ *
+ * The shape derivation stays for `null` — a row written before the column
+ * existed, for which no fact was recorded and an inference is all there is.
+ *
+ * Three sites post that pending status, and the derivation is read off them
+ * rather than off the queue type — which cannot make the distinction, because a
+ * workflow install gate whose context protection rule is security-typed carries
+ * `queue_type = 'security'` and posts nothing at all.
+ *
+ * | Hold | Written by | Posts pending? | Recognised here by |
+ * |---|---|---|---|
+ * | org trust policy's PR-wide hold | `holdRunForSecurityPolicy` | yes | `job_id` is a `SECURITY_HOLD_JOB_IDS` sentinel |
+ * | workflow install gate | `holdWorkflowForInstallGate` | no | `job_id` is `installGateJobId(name)` |
+ * | SDK workflow `requireApproval` | `holdJobForApproval` | yes | carries an `approval_requirement` |
+ * | context reviewer hold | `holdJobForApproval` | yes | carries an `approval_requirement` |
+ * | SDK job `requireApproval` | `holdJobForApproval` | yes | carries an `approval_requirement` |
+ * | context security hold | the per-env gate | yes | job scope + `hold_type = security` |
+ * | wait-timer / concurrency hold | the per-env gate | no | none of the above matches |
+ * | step approval | `StepApprovalBridge.request` | no | step scope |
+ *
+ * `approval_requirement` is what `createHold` writes and `create` does not, so
+ * it identifies exactly the rows `holdJobForApproval` wrote through the
+ * approval path — the site whose post is guarded by `if (hold && …)`. The two
+ * other `createHold` callers are excluded above it: the install gate by its job
+ * id, the step bridge by its scope.
+ */
+export declare function postedPendingSecurityCheck(hold: SecurityCheckHold): boolean;
+/**
+ * The terminal summary for a hold that ended, in the one vocabulary both check
+ * families use: `cancelled` for a rejection, `timed_out` for an elapsed window,
+ * `success` for an approval.
+ *
+ * The subject follows the hold's scope on every outcome, because the same event
+ * means different things at each: a workflow-scoped hold owns the whole run,
+ * while a job-scoped one owns one job and says nothing about the run's other
+ * jobs — including a step-approval hold that is still pending, which a run-wide
+ * "no longer waiting for approval" would contradict.
+ *
+ * `actor` names whoever ended the hold, on an approve and on a reject alike.
+ * Only an expiry has none: nobody answered, which is what expiry means. A
+ * rejecter whose surface already writes its own attribution into `reason` (the
+ * `/kici reject` handler builds "Rejected by alice via /kici reject") passes no
+ * `actor`, so the sentence lands once rather than twice.
+ *
+ * **`actor` is a display name, and it is published verbatim on a public commit
+ * check.** It must never be an opaque identity-provider subject id: a surface
+ * that holds one — the dashboard / CLI / MCP applier, which decides by KiCI
+ * user id — resolves it against the org's identity directory first and passes
+ * nothing when that resolves to no single name. Omitting the attribution reads
+ * as "an approver"; leaking the subject reads as `Approved by
+ * 8f3a-…-uuid`, on a pull request anyone can open.
+ *
+ * `reason` is normalized to end in terminal punctuation — a rejecter's own
+ * sentence carries none, and without one it runs straight into what follows.
+ */
+export declare function buildHoldEndedSummary(args: {
+    outcome: HoldOutcome;
+    scope: string;
+    reason?: string | undefined;
+    actor?: string | undefined;
+    via?: string | undefined;
+}): string;
+/**
+ * Terminalize the `KiCI Security` check of a hold that just ended, choosing the
+ * conclusion, title and summary from {@link HoldOutcome}.
+ *
+ * The single entry point for every surface that ends a hold — the `/kici`
+ * comment handler, the dashboard / CLI / MCP applier, and the stale detector's
+ * approval-window sweep — so those surfaces cannot render one event three ways.
+ */
+export declare function settleSecurityCheckForOutcome(args: {
+    db: Kysely<Database> | undefined;
+    resolvePoster: ResolveCheckStatusPoster | undefined;
+    hold: SecurityCheckHold;
+    outcome: HoldOutcome;
+    reason?: string | undefined;
+    actor?: string | undefined;
+    via?: string | undefined;
+    excludeHoldIds?: readonly string[] | undefined;
+    skipCommits?: ReadonlySet<string> | undefined;
+}): Promise<SettleSecurityCheckResult>;
+/**
+ * The dashboard / CLI / MCP applier's entry point into
+ * {@link settleSecurityCheckForOutcome}.
+ *
+ * That applier decides by KiCI user id, so the only actor it holds is an opaque
+ * identity-provider subject — and this summary is published verbatim on a public
+ * commit check. `resolveDisplayName` maps the subject onto the account name the
+ * org's identity directory links it to; when it names none, the attribution is
+ * DROPPED rather than falling back to the subject. So an approve reads
+ * "Approved by an approver" at worst, never "Approved by 8f3a-…-uuid".
+ *
+ * Separate from its caller so the resolve-or-drop step is a unit under test
+ * rather than a line in the composition root.
+ */
+export declare function settleSecurityCheckForDecision(args: {
+    db: Kysely<Database> | undefined;
+    resolvePoster: ResolveCheckStatusPoster | undefined;
+    /** Subject id → the linked account name, or undefined for no single name. */
+    resolveDisplayName: (actorSub: string) => string | undefined;
+    hold: SecurityCheckHold;
+    outcome: HoldOutcome;
+    /** Omitted where the summary must match one another writer built without it. */
+    actorSub?: string | undefined;
+    reason?: string | undefined;
+}): Promise<SettleSecurityCheckResult>;
+/**
+ * Terminalize the `KiCI Security` check of a hold that just ended, under a
+ * caller-supplied status and copy.
+ *
+ * Used directly where one summary has to reach BOTH check families — a rejected
+ * workflow-scoped hold reports the same sentence on `KiCI Security` and on the
+ * `kici/…` runs of the same event, and that sameness is asserted rather than
+ * assumed. Everything else goes through {@link settleSecurityCheckForOutcome}.
+ *
+ * Call it AFTER the hold's own row has left `pending` (every caller does: the
+ * applier flips inside `recordAndReject` / `recordAndRelease`, the comment
+ * handler inside `reject` / `approveByQueueType`) — and, on an approve, BEFORE
+ * the resume, so a replayed dispatch that holds again overwrites this terminal
+ * status with its own pending one rather than the other way round. The ending
+ * hold's own id is excluded from the contention query regardless, so a sweep
+ * that has not yet flipped its batch can name it in `excludeHoldIds`.
+ *
+ * Never throws: terminalizing a check run is a reporting courtesy on a path
+ * whose real job is to terminalize the hold, and a provider error must not stop
+ * that. The returned `posted` is what a caller binds its own suppression to —
+ * it says a check was written, not merely that a delegate resolved.
+ */
+export declare function settleSecurityHoldCheck(args: {
+    db: Kysely<Database> | undefined;
+    resolvePoster: ResolveCheckStatusPoster | undefined;
+    hold: SecurityCheckHold;
+    status: CheckStatus;
+    title: string;
+    summary: string;
+    excludeHoldIds?: readonly string[] | undefined;
+    /**
+     * Commits this caller already wrote in the same pass. A sweep that ends
+     * several holds on one commit shares one check run between them, and every
+     * hold in it carries the same conclusion and summary — so the second write
+     * would be a byte-identical provider round-trip.
+     */
+    skipCommits?: ReadonlySet<string> | undefined;
+}): Promise<SettleSecurityCheckResult>;
+//# sourceMappingURL=security-hold-check.d.ts.map

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

@@ -22,6 +22,7 @@
  * - direct workflow execution (bypass trigger matching) is supported.
  */
 import { type ProcessingDeps } from './processor.js';
+import { type ActorPrincipal } from '@kici-dev/engine';
 import type { CheckMode, HostTargetSelector } from '@kici-dev/engine';
 /**
  * Input for a test trigger request.
@@ -58,6 +59,17 @@ export interface TestTriggerInput {
     };
     /** Request trace ID from the HTTP request. */
     requestId: string;
+    /**
+     * The principal that initiated this run, relayed by the Platform on
+     * `test.relay.trigger` (where the wire schema has always required it).
+     *
+     * Required rather than optional: the relay handler is the only production
+     * caller, so there is no path that legitimately lacks an actor, and an
+     * optional field would let a future caller silently drop attribution — which
+     * is exactly how `execution_runs.triggered_by` stayed NULL for every remote
+     * test run while the column claimed to hold the initiator.
+     */
+    actor: ActorPrincipal;
     /** JSON-stringified lock file content for local repos with no remote. */
     inlineLockFile?: string;
     /** When true, repo has no remote -- skip provider lookup, skip clone. */

package/dist/pipeline/undispatched-hold-checks.d.ts

@@ -0,0 +1,23 @@
+import { type CheckRunConclusion } from '@kici-dev/engine';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { CheckRunReporter } from '../reporting/check-run-reporter.js';
+/**
+ * Complete the check runs of `runId`'s stored workflow dispatch, if it has one.
+ *
+ * A run with no pending workflow context never held at workflow scope (or its
+ * context was already consumed by a resume), so there is nothing to close and
+ * this is a no-op. Call it BEFORE `deletePendingWorkflowContext` — the context
+ * is the only place the check-run names can still be derived from.
+ *
+ * Never throws: closing a check run is a reporting courtesy on a path whose real
+ * job is to terminalize the run, and a provider error must not stop that.
+ */
+export declare function completeUndispatchedHoldChecks(args: {
+    db: Kysely<Database> | undefined;
+    checkRunReporter: CheckRunReporter | undefined;
+    runId: string;
+    conclusion: CheckRunConclusion;
+    summary: string;
+}): Promise<void>;
+//# sourceMappingURL=undispatched-hold-checks.d.ts.map

package/dist/pipeline/webhook-payload-store.d.ts

@@ -0,0 +1,20 @@
+import type { LogStorage } from '../reporting/log-storage.js';
+/**
+ * Object-storage key holding the webhook payload for a run. Shared by the
+ * writers and by the re-run path that copies a payload forward, so the layout
+ * is stated once.
+ */
+export declare function webhookPayloadPath(runId: string): string;
+/**
+ * Store a run's triggering webhook payload, best-effort.
+ *
+ * A failure is logged and swallowed: the payload is a debugging aid, and losing
+ * it must never cost the run that was about to execute. A no-op when the
+ * orchestrator has no object storage configured.
+ */
+export declare function storeWebhookPayload(args: {
+    logStorage: LogStorage | undefined;
+    runId: string;
+    payload: unknown;
+}): Promise<void>;
+//# sourceMappingURL=webhook-payload-store.d.ts.map

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

@@ -0,0 +1,62 @@
+/**
+ * Cross-coordinator propagation of dashboard-write policy changes.
+ *
+ * Sister to `GenericSourcesChangeListener`
+ * (`packages/orchestrator/src/webhook/generic-sources-listener.ts`), which
+ * owns the `generic_sources_change` channel. This listener owns
+ * `dashboard_write_policy_change` — the channel `setDashboardWritePolicy`
+ * emits from inside its own write transaction.
+ *
+ * The problem it solves: `dashboardWritePolicyEvents` is a per-process
+ * `EventEmitter`, so only the coordinator that served the `kici-admin`
+ * write learned about a flip. Its siblings kept serving a stale cached map
+ * from their own policy gate for up to the cache TTL, and — worse — kept
+ * advertising the stale map to the control plane indefinitely, because
+ * capabilities are pushed on change and on reconnect, never polled. The
+ * control plane caches capabilities per orchestrator connection and resolves
+ * a cluster name to whichever of its connections it finds first, so a policy
+ * flip could be invisible to the dashboard for as long as the cluster stayed
+ * up.
+ *
+ * On NOTIFY:
+ *   1. Queue the affected `customer_id` (the channel payload).
+ *   2. Debounce 200 ms so rapid flips coalesce into one drain pass.
+ *   3. For each queued customer: drop the cached map, re-read the
+ *      authoritative one from the database, and emit `'changed'` on
+ *      `dashboardWritePolicyEvents`. The platform-mode boot already
+ *      subscribes to that event and re-broadcasts `orch.capabilities`.
+ *
+ * The payload is the customer id alone: every coordinator shares one
+ * orchestrator database, so re-reading is both cheap and authoritative,
+ * and no wire copy of the map can go stale in flight.
+ *
+ * The writing coordinator receives its own NOTIFY too. That is deliberate
+ * and harmless — it already emitted the event in-process, and the second
+ * emit produces an identical capability broadcast.
+ */
+import type pg from 'pg';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+export interface DashboardWritePolicyChangeListenerOptions {
+    /** Raw pg pool — a dedicated PoolClient is checked out for LISTEN. */
+    pool: pg.Pool;
+    /** Used to re-read the authoritative policy map on each NOTIFY. */
+    db: Kysely<Database>;
+    /** Coalesce window for rapid NOTIFYs against the same customer. Default 200 ms. */
+    debounceMs?: number;
+}
+export declare class DashboardWritePolicyChangeListener {
+    private readonly opts;
+    private client;
+    private readonly pending;
+    private debounceTimer;
+    private readonly debounceMs;
+    constructor(opts: DashboardWritePolicyChangeListenerOptions);
+    /** Open the dedicated client and subscribe. */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private scheduleDrain;
+    /** Visible for tests — drain the queued customer ids synchronously. */
+    drain(): Promise<void>;
+}
+//# sourceMappingURL=dashboard-write-policy-listener.d.ts.map

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

@@ -23,10 +23,24 @@ 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';
+/**
+ * Postgres `LISTEN/NOTIFY` channel carrying policy changes across the
+ * cluster. The payload is the `customer_id` alone — every coordinator
+ * shares one orchestrator database, so each listener re-reads the
+ * authoritative map for itself rather than trusting a wire copy.
+ *
+ * `DashboardWritePolicyChangeListener` (`./dashboard-write-policy-listener.ts`)
+ * is the consumer.
+ */
+export declare const DASHBOARD_WRITE_POLICY_CHANNEL = "dashboard_write_policy_change";
 /**
  * Event bus for policy-change notifications. The WS publisher subscribes
  * to `'changed'` so it can broadcast a fresh `orch.capabilities` to
  * Platform whenever the operator flips a switch.
+ *
+ * The emitter is per-process, so it carries a change only to the peer that
+ * served the admin write. The NOTIFY channel above is what reaches the other
+ * coordinators, whose listeners then emit this same event locally.
  */
 export declare const dashboardWritePolicyEvents: EventEmitter<[never]>;
 /**

package/dist/provenance/backfill-run.d.ts

@@ -6,6 +6,12 @@ export interface BackfillRunRow {
     status: string;
     routing_key: string | null;
     repo_identifier: string | null;
+    /**
+     * The repository that DEFINES the workflow, recorded only when it differs
+     * from `repo_identifier`. A cross-repository global run backfilled without it
+     * lands in the Platform mirror as an ordinary per-repository run.
+     */
+    workflow_repo_identifier: string | null;
     provider: string | null;
     local_working_tree: boolean | null;
     sha: string | null;
@@ -33,7 +39,10 @@ export interface BackfillRunDeps {
 }
 /**
  * Send one `execution.status` (terminal) followed by one `job.status.forward`
- * per job, populating exactly the fields the Platform's `handler.ts` upserts.
+ * per job, populating the run and job fields the Platform's `handler.ts` upserts
+ * that the local rows can answer for (the trigger metadata a live run carries in
+ * memory — trigger event, commit message, re-run lineage — has no column here
+ * and is left to the live path).
  * Ordered execution.status FIRST so the run row exists before the job rows
  * reference it. A no-op (throws) when the run is not found locally — the caller
  * leaves the pending row `deferred` with a clear error.

package/dist/provider-registry.d.ts

@@ -12,7 +12,7 @@
  * webhook normalization, lock file fetching, changed files retrieval,
  * clone token creation, and URL building.
  */
-import type { WebhookNormalizer, LockFileFetcher, ChangedFilesFetcher, CloneTokenProvider, RepoUrlBuilder, ContributorResolver, CheckStatusPoster, ProviderType } from '@kici-dev/engine';
+import type { WebhookNormalizer, LockFileFetcher, FileContentsFetcher, ChangedFilesFetcher, CloneTokenProvider, RepoUrlBuilder, CheckStatusPoster, ProviderType } from '@kici-dev/engine';
 /**
  * Complete set of provider capabilities.
  *
@@ -24,10 +24,35 @@ import type { WebhookNormalizer, LockFileFetcher, ChangedFilesFetcher, CloneToke
 export interface ProviderBundle {
     normalizer: WebhookNormalizer;
     lockFileFetcher?: LockFileFetcher;
+    /**
+     * Fetches arbitrary file contents at a ref (content-match triggers). Unlike
+     * the other fetchers, a GitHub instance is scoped to one installation, so the
+     * per-delivery installation id must be known to construct it -- it is wired
+     * where that id is in scope, not in the source-level bundle build. Providers
+     * that can prebuild one (no per-delivery credential) may set this directly;
+     * providers scoped per installation supply {@link fileContentsFetcherFactory}
+     * instead.
+     */
+    fileContentsFetcher?: FileContentsFetcher;
+    /**
+     * Builds a per-delivery {@link FileContentsFetcher} from the event
+     * credentials (e.g. a GitHub installation id). Returns undefined when the
+     * credentials do not carry what the provider needs. The webhook pipeline
+     * calls this once per delivery, where the credentials are already resolved.
+     */
+    fileContentsFetcherFactory?: (credentials: Record<string, unknown>) => FileContentsFetcher | undefined;
     changedFilesFetcher?: ChangedFilesFetcher;
     cloneTokenProvider?: CloneTokenProvider;
     repoUrlBuilder?: RepoUrlBuilder;
-    contributorResolver?: ContributorResolver;
+    /**
+     * This provider has a fork model: a head ref can live outside the base repo,
+     * so the fork trust policy applies to its pull-request events. True for
+     * GitHub. Absent for providers whose trust boundary is something else — a
+     * generic source's verification secret, a local source's on-disk ownership —
+     * and for universal-git, which reports an `isForkPR` signal that must not
+     * gate it.
+     */
+    hasForkModel?: boolean;
     checkStatusPoster?: CheckStatusPoster;
     /**
      * Local `file://` in-place profile: this bundle's `repoBasePath` is the
@@ -79,12 +104,30 @@ export declare class ProviderRegistry {
      * prefix. For multi-app, use getByRoutingKey() instead.
      */
     get(type: ProviderType): ProviderBundle | undefined;
+    /**
+     * Whether a bundle is registered at EXACTLY this routing key.
+     *
+     * `getByRoutingKey` cannot answer this: it falls back to a provider-type
+     * lookup, so it returns a bundle for a key it has never seen. A caller that
+     * needs to know whether the source's OWN bundle is present — rather than
+     * whether some bundle can be produced — has to ask here.
+     */
+    hasExact(routingKey: string): boolean;
     /**
      * Get the provider bundle by routing key.
      * Routing keys have the format "{provider}:{id}" (e.g., "github:12345").
      *
-     * Falls back to get(providerType) if exact key is not found,
-     * for backward compatibility with single-app registration.
+     * Falls back to get(providerType) if the exact key is not found, for
+     * backward compatibility with single-app registration.
+     *
+     * The fallback is deliberately narrower for a `generic:` key. Such a key is
+     * fully qualified (`generic:{orgId}:{sourceId}`), so the type-prefix scan in
+     * `get()` cannot be a "the single configured app" shortcut the way it is for
+     * `github:` — it returns whichever `generic:`-prefixed bundle happens to sit
+     * first in insertion order, which may belong to a different source, or to a
+     * different ORGANIZATION. Only the shared default bundle (`generic:default`,
+     * the one that genuinely stands in for every plain generic source) is an
+     * acceptable stand-in, so that is the only fallback offered here.
      */
     getByRoutingKey(routingKey: string): ProviderBundle | undefined;
     /**

package/dist/providers/github/check-status-poster.d.ts

@@ -5,11 +5,13 @@
  * - Security holds (pending): "KiCI Security" — "Held for approval"
  * - Workflow modifications (neutral): "KiCI: Workflow changes"
  * - Org globals skipped by the trust policy (neutral): "KiCI: Organization workflows"
+ * - Org global evaluation failed (failure): "KiCI: Organization workflow evaluation"
  * - Approved runs (success) / Rejected/expired runs (failure)
  *
- * `postWorkflowModificationCheck` and `postGlobalWorkflowsSkippedCheck` are
- * interface-backed (the `CheckStatusPoster` contract in `@kici-dev/engine`) and
- * post on their own check names so neither overwrites the security-hold check.
+ * `postWorkflowModificationCheck`, `postGlobalWorkflowsSkippedCheck`, and
+ * `postGlobalEvalFailedCheck` are interface-backed (the `CheckStatusPoster`
+ * contract in `@kici-dev/engine`) and post on their own check names so none of
+ * them overwrites the security-hold check.
  *
  * Reuses the Octokit infrastructure from auth.ts via createInstallationOctokit.
  * Uses a fixed check name per category so that subsequent updates (approve/reject)
@@ -47,5 +49,33 @@ export declare class GitHubCheckStatusPoster implements CheckStatusPoster {
      * while the run is still held. Always posted as neutral/completed.
      */
     postGlobalWorkflowsSkippedCheck(repoIdentifier: string, commitSha: string, summary: string, credentials: unknown): Promise<void>;
+    /**
+     * Post the check recording that the pre-run evaluation of the organization's
+     * global workflows failed, so none of the workflows it was deciding on ran.
+     *
+     * Its own check name ("KiCI: Organization workflow evaluation") for the same
+     * reason as the notice above: the security-hold check is a single named run
+     * per commit which a hold posts as pending and approve / reject later
+     * complete, so writing this through `postCheckStatus` would resolve a
+     * still-held run's check and unblock a branch protection rule that requires
+     * it.
+     *
+     * Posted as a failure, not a neutral: work the organization asked for did not
+     * run, and the reader has to be able to tell that from a clean commit. The
+     * name is new, so no existing branch protection rule requires it — a rule
+     * only requires check names it was configured with.
+     */
+    postGlobalEvalFailedCheck(repoIdentifier: string, commitSha: string, summary: string, credentials: unknown): Promise<void>;
+    /**
+     * Post the success conclusion on the organization-workflow-evaluation check
+     * after a re-run of a failed round completed cleanly.
+     *
+     * Deliberately the SAME check name the failure posts: GitHub keys a check run
+     * by its name on a commit, so writing the success under that name is what
+     * turns the red check green on the original commit. A second, differently
+     * named green check would leave the red one standing and keep a branch
+     * protection rule blocked with no way to clear it short of a new commit.
+     */
+    postGlobalEvalSucceededCheck(repoIdentifier: string, commitSha: string, summary: string, credentials: unknown): Promise<void>;
 }
 //# sourceMappingURL=check-status-poster.d.ts.map

package/dist/providers/github/commit-message.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Where the commit message lives in a GitHub webhook payload, and the two
+ * different readings of it.
+ *
+ * They differ deliberately. `githubFilterText` feeds the Tier-0 `commitMessage`
+ * trigger filter, so it must be the WHOLE message — truncating to the subject
+ * line would make a `[skip ci]` marker written in the body invisible to a filter
+ * that names it. `githubDisplayMessage` feeds run-display metadata, where a
+ * one-line summary is the point.
+ */
+/** Full text a `commitMessage` trigger filter is tested against; undefined when the payload carries none. */
+export declare function githubFilterText(event: string, payload: unknown): string | undefined;
+/**
+ * One-line message for run display: the subject (first line) of a push's
+ * head-commit message, the PR title, or the issue title. This is the reading
+ * run-display metadata uses, distinct from the full text `githubFilterText`
+ * feeds the Tier-0 filter.
+ */
+export declare function githubDisplayMessage(event: string, payload: unknown): string | undefined;
+//# sourceMappingURL=commit-message.d.ts.map

package/dist/providers/github/file-contents.d.ts

@@ -0,0 +1,40 @@
+/**
+ * GitHub file contents fetcher.
+ *
+ * Implements the FileContentsFetcher interface from @kici-dev/engine for GitHub.
+ * Fetches an arbitrary file's contents from a GitHub repository at a specific
+ * ref via the Contents API, so the orchestrator can evaluate content-match
+ * triggers without cloning the repo.
+ */
+import type { FileContentsFetcher } from '@kici-dev/engine';
+import { type GitHubAppConfig } from './auth.js';
+/**
+ * GitHub-specific implementation of FileContentsFetcher.
+ *
+ * The installation id is baked in at construction because the
+ * FileContentsFetcher interface is credential-less at call time -- a fetcher
+ * instance is scoped to one GitHub App installation.
+ */
+export declare class GitHubFileContentsFetcher implements FileContentsFetcher {
+    private readonly config;
+    private readonly installationId;
+    readonly provider: 'github';
+    constructor(config: GitHubAppConfig, installationId: number);
+    /**
+     * Fetch a file's contents from a GitHub repository at a specific ref.
+     *
+     * @param owner - Repository owner (e.g. "my-org")
+     * @param repo - Repository name (e.g. "my-app")
+     * @param path - Repo-relative file path (e.g. ".kici/workflows/ci.ts")
+     * @param ref - Git ref (branch, tag, or SHA)
+     * @returns `{ present: false }` on 404 / directory; `{ present: true, bytes }`
+     *          when inline content is returned; `{ present: true }` (no bytes)
+     *          when the file exists but GitHub omits inline content (files over
+     *          1 MiB).
+     */
+    getFileContents(owner: string, repo: string, path: string, ref: string): Promise<{
+        present: boolean;
+        bytes?: string;
+    }>;
+}
+//# sourceMappingURL=file-contents.d.ts.map

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

@@ -4,17 +4,17 @@
  * Each class implements a corresponding interface from @kici-dev/engine:
  * - GitHubWebhookNormalizer -> WebhookNormalizer
  * - GitHubLockFileFetcher -> LockFileFetcher
+ * - GitHubFileContentsFetcher -> FileContentsFetcher
  * - GitHubChangedFilesFetcher -> ChangedFilesFetcher
  * - GitHubCloneTokenProvider -> CloneTokenProvider
  * - GitHubRepoUrlBuilder -> RepoUrlBuilder
- * - GitHubContributorResolver -> ContributorResolver
  */
 export { GitHubWebhookNormalizer } from './normalizer.js';
 export { GitHubLockFileFetcher } from './lock-file.js';
+export { GitHubFileContentsFetcher } from './file-contents.js';
 export { GitHubChangedFilesFetcher } from './changed-files.js';
 export { GitHubCloneTokenProvider, createInstallationOctokit } from './auth.js';
 export type { GitHubAppConfig, GitHubCredentials } from './auth.js';
 export { GitHubRepoUrlBuilder } from './repo-url.js';
-export { GitHubContributorResolver } from './contributor-resolver.js';
 export { GitHubCheckStatusPoster } from './check-status-poster.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -74,8 +74,9 @@ export declare class GitHubWebhookNormalizer implements WebhookNormalizer {
      */
     extractCredentials(payload: unknown): Record<string, unknown>;
     /**
-     * Map GitHub membership-related webhook events to ContributorCache
-     * invalidations. See WebhookNormalizer.getAccessCacheInvalidations.
+     * Map GitHub membership-related webhook events to permission-cache
+     * invalidations. See WebhookNormalizer.getAccessCacheInvalidations, which is
+     * deprecated and has no caller.
      *
      * Covered event types:
      *

package/dist/providers/local/normalizer.d.ts

@@ -70,8 +70,9 @@ export declare class LocalWebhookNormalizer implements WebhookNormalizer {
      */
     normalizeEvent(eventType: string, _action: string | null, payload: unknown): SimulatedEvent | null;
     /**
-     * Map membership-related local-source webhook events to ContributorCache
-     * invalidations.
+     * Map membership-related local-source webhook events to permission-cache
+     * invalidations. See WebhookNormalizer.getAccessCacheInvalidations, which is
+     * deprecated and has no caller.
      *
      * Local-source payloads are GitHub-shaped by design, so the mapping
      * mirrors the GitHub normalizer exactly:
@@ -80,9 +81,6 @@ export declare class LocalWebhookNormalizer implements WebhookNormalizer {
      * - `organization`: user-in-org
      * - `membership`: user-in-org
      * - `team` (repo-scoped actions only): repo
-     *
-     * This lets membership-invalidation paths be exercised through
-     * `sendLocalWebhook()` without requiring a real GitHub App.
      */
     getAccessCacheInvalidations(eventType: string, _action: string | null, payload: unknown): AccessCacheInvalidation[];
 }