@kici-dev/orchestrator 0.1.27 → 0.2.0

package/dist/pipeline/resolve-sandbox-grant.d.ts

@@ -0,0 +1,28 @@
+import type { ResolvedSandboxGrant, SandboxNetworkMode } from '@kici-dev/engine';
+import type { SandboxAllowList } from './sandbox-allowlist-reader.js';
+/** The workflow-declared per-job escape-hatch request carried in the lock. */
+export interface SandboxRequest {
+    capabilities?: string[];
+    network?: SandboxNetworkMode;
+}
+/**
+ * The resolution outcome: either an authorized grant (possibly `undefined` when
+ * the request is a no-op / non-escalating) or a total, loud denial.
+ */
+export type SandboxGrantResolution = {
+    grant?: ResolvedSandboxGrant;
+} | {
+    denied: {
+        reason: string;
+    };
+};
+/**
+ * Resolve a workflow-declared sandbox request against the operator's allow-list
+ * (the single enforcement point). Deny is loud and total — a request for any
+ * capability or host-network the operator did not allow-list fails the run with
+ * a reason naming the offending cap/knob; a disallowed cap is never silently
+ * stripped and run anyway. Pure (no I/O), so the allow-list is injected and the
+ * function is exhaustively unit-testable.
+ */
+export declare function resolveSandboxGrant(request: SandboxRequest | undefined, allowList: SandboxAllowList): SandboxGrantResolution;
+//# sourceMappingURL=resolve-sandbox-grant.d.ts.map

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

@@ -0,0 +1,71 @@
+/**
+ * Shared coordinator-route / direct-dispatch machinery for the orchestrator
+ * pipeline.
+ *
+ * The re-run path (`rerun.ts`) and the manual-schedule path
+ * (`manual-schedule.ts`) both materialize a workflow's static jobs, try to
+ * route them through the cluster coordinator (local dispatch first, then
+ * reroute to peers), fall back to direct local dispatch in standalone mode or
+ * on a coordinator timeout, and synthesize records for rejected jobs. This
+ * module implements that once so a fix lands in a single place.
+ */
+import { createLogger } from '@kici-dev/shared';
+import type { LockJob, MaterializedJob } from '@kici-dev/engine';
+import type { RunContext, RunCoordinator } from '../cluster/coordinator.js';
+import type { Dispatcher } from '../agent/dispatcher.js';
+import type { ExecutionTracker } from '../reporting/execution-tracker.js';
+export interface DispatchedJobEntry {
+    jobId: string;
+    jobName: string;
+    matrixValues?: Record<string, unknown>;
+    runsOnLabels?: string[];
+}
+export interface RejectedJobEntry {
+    jobId: string;
+    reason: string;
+}
+export interface RouteOrDispatchOptions {
+    newRunId: string;
+    /** Static jobs before materialization — the helper materializes + handles FanoutError. */
+    staticJobs: LockJob[];
+    workflowName: string;
+    repoUrl: string;
+    ref: string;
+    sha: string;
+    deliveryId: string;
+    provider: string;
+    providerContext: Record<string, unknown>;
+    routingKey: string;
+    /** Prebuilt by the caller (event name / payload / installationId differ per path). */
+    runContext: RunContext;
+    /** Per-caller jobConfig shape (schedule dispatchInputs vs. rerun source fallback). */
+    buildJobConfig: (mat: MaterializedJob) => Record<string, unknown>;
+    /** Caller's own logger — keeps the originating prefix ('manual-schedule' / 'rerun'). */
+    logger: ReturnType<typeof createLogger>;
+    /** Human label used in log messages: 'Manual schedule' | 'Re-run'. */
+    label: string;
+    coordinator: RunCoordinator | null;
+    dispatcher: Dispatcher;
+}
+/**
+ * Materialize the static jobs (degrading gracefully on a matrix that can no
+ * longer expand), then route them via the coordinator or, in standalone mode /
+ * on a coordinator timeout, dispatch directly. Returns the jobs to register
+ * with the execution tracker plus any synthetic-rejected IDs to mark failed.
+ */
+export declare function routeOrDispatchJobs(opts: RouteOrDispatchOptions): Promise<{
+    dispatchedJobs: DispatchedJobEntry[];
+    rejectedJobs: RejectedJobEntry[];
+}>;
+export interface RegisterDispatchedJobsOptions {
+    newRunId: string;
+    dispatchedJobs: DispatchedJobEntry[];
+    rejectedJobs: RejectedJobEntry[];
+    executionTracker: ExecutionTracker;
+}
+/**
+ * Register dispatched jobs with the execution tracker, then mark any
+ * synthetic-rejected jobs failed. No-op when nothing was dispatched.
+ */
+export declare function registerDispatchedJobs(opts: RegisterDispatchedJobsOptions): Promise<void>;
+//# sourceMappingURL=route-or-dispatch-jobs.d.ts.map

package/dist/pipeline/sandbox-allowlist-reader.d.ts

@@ -0,0 +1,33 @@
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+/**
+ * The operator-controlled per-org escape-hatch allow-list. `capabilities` are
+ * stored canonicalized (bare uppercase Docker-API form) so the dispatch resolver
+ * compares canonical-to-canonical.
+ */
+export interface SandboxAllowList {
+    capabilities: string[];
+    allowHostNetwork: boolean;
+}
+export interface SandboxAllowListReader {
+    /**
+     * Read the org's escape-hatch allow-list. Never throws; on a DB error (or no
+     * DB handle) it degrades to the safe deny-all default `{ capabilities: [],
+     * allowHostNetwork: false }` so a sick DB denies escalation rather than
+     * blocking dispatch.
+     */
+    read(orgId: string): Promise<SandboxAllowList>;
+}
+/**
+ * Reader for the per-org container-sandbox escape-hatch allow-list. Read once per
+ * matched-workflow dispatch (not per request), against a single indexed row, so
+ * it is intentionally **uncached**: this is a security control, and an operator's
+ * `sandbox-allowlist` change must take effect on the very next dispatch (a cache
+ * would leave the old policy in force for its TTL — a stale-deny or stale-allow
+ * window on a privilege boundary). The trivial per-dispatch query is the right
+ * trade for always-fresh enforcement.
+ */
+export declare function createSandboxAllowListReader(deps: {
+    db?: Kysely<Database>;
+}): SandboxAllowListReader;
+//# sourceMappingURL=sandbox-allowlist-reader.d.ts.map

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

@@ -20,7 +20,7 @@
  */
 import { EventEmitter } from 'node:events';
 import { type Kysely } from 'kysely';
-import { DashboardWriteOperation, type DashboardWritePolicyMap } from '@kici-dev/engine/protocol/dashboard-write-operations';
+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';
 /**
@@ -37,7 +37,7 @@ export declare const dashboardWritePolicyEvents: EventEmitter<[never]>;
 export declare class DashboardWritePolicyDisabledError extends Error {
     readonly operation: DashboardWriteOperation;
     readonly cliEquivalent: string;
-    readonly code: "operation_disabled";
+    readonly code: 'operation_disabled';
     constructor(operation: DashboardWriteOperation, cliEquivalent: string);
 }
 /**
@@ -64,6 +64,11 @@ export declare function getDashboardWritePolicy(db: Kysely<Database>, customerId
  * `getDashboardWritePolicy` + the engine-side resolver.
  */
 export declare function isDashboardWriteEnabled(db: Kysely<Database>, customerId: string, op: DashboardWriteOperation): Promise<boolean>;
+/**
+ * Resolve the tri-state posture (`permissive` | `encrypted` | `disabled`) for
+ * an operation. Reads through the same 30 s cache as the enabled check.
+ */
+export declare function getDashboardWritePolicyState(db: Kysely<Database>, customerId: string, op: DashboardWriteOperation): Promise<DashboardWritePolicyState>;
 /**
  * Defense-in-depth gate for orch-side dashboard.* handlers. Throws
  * `DashboardWritePolicyDisabledError` when the operation is disabled.
@@ -100,8 +105,8 @@ export interface PolicyChangeEvent {
     actor: ActorPrincipal;
     customerId: string;
     op: DashboardWriteOperation;
-    prior: boolean;
-    next: boolean;
+    prior: DashboardWritePolicyState;
+    next: DashboardWritePolicyState;
 }
 /**
  * Reset to the permissive defaults (everything enabled). Useful for

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

@@ -4,6 +4,7 @@ export interface BackfillRunRow {
     run_id: string;
     workflow_name: string;
     status: string;
+    routing_key: string | null;
     repo_identifier: string | null;
     provider: string | null;
     local_working_tree: boolean | null;

package/dist/provenance/trust-root.d.ts

@@ -16,6 +16,19 @@ export interface ProvenanceTrustRoot {
     getJwks(kid?: string): Promise<JSONWebKeySet | null>;
     setIssuer(issuer: string | null): void;
 }
+/**
+ * A trust root backed by the orchestrator's OWN signing keys (Phase 1
+ * orchestrator-owned attestations). Verify-at-ingest resolves the key set from
+ * the `orchestrator_signing_keys` table so fresh rotations / revocations are
+ * reflected immediately, and the issuer is the orchestrator's own configured
+ * provenance issuer. The key set is read fresh from the DB each resolve (a cheap
+ * read; ingest verification is not hot), so a rotated-in `kid` is always found.
+ */
+export declare function provenanceTrustRootFromRepo(repo: {
+    listTrusted: () => Promise<{
+        public_jwk: unknown;
+    }[]>;
+}, issuer: string): ProvenanceTrustRoot;
 export declare function createProvenanceTrustRoot(opts?: {
     issuer?: string | null;
     fetchImpl?: typeof fetch;

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

@@ -17,7 +17,7 @@ import type { GenericSourceManager } from '../../webhook/generic-sources.js';
  */
 export declare class GenericWebhookNormalizer implements WebhookNormalizer {
     private readonly sourceManager;
-    readonly provider: "generic";
+    readonly provider: 'generic';
     constructor(sourceManager: GenericSourceManager);
     /**
      * Extract routing key from the X-KiCI-Source-ID header.

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

@@ -44,7 +44,7 @@ export declare function createInstallationOctokit(config: GitHubAppConfig, insta
  */
 export declare class GitHubCloneTokenProvider implements CloneTokenProvider {
     private readonly config;
-    readonly provider: "github";
+    readonly provider: 'github';
     constructor(config: GitHubAppConfig);
     /** Get the GitHub App config for this provider instance. */
     getAppConfig(): GitHubAppConfig;

package/dist/providers/github/changed-files.d.ts

@@ -4,7 +4,7 @@
  * Implements the ChangedFilesFetcher interface from @kici-dev/engine for GitHub.
  * Retrieves changed files for PR and push events via the GitHub API.
  */
-import type { ChangedFilesFetcher } from '@kici-dev/engine';
+import type { ChangedFilesFetcher, ChangedFilesResult } from '@kici-dev/engine';
 import { type GitHubAppConfig } from './auth.js';
 /**
  * Check if an error is a GitHub 429 rate limit response.
@@ -12,9 +12,17 @@ import { type GitHubAppConfig } from './auth.js';
  */
 export declare function isRateLimitError(err: unknown): boolean;
 /**
- * Execute a function with retry on 429 rate limit errors.
- * Uses exponential backoff: 1s, 2s, 4s.
- * Non-429 errors are rethrown immediately.
+ * Check if an error is a transient GitHub 5xx server error worth retrying.
+ * A pure network error (no numeric `status`) is deliberately NOT transient
+ * here — it rethrows immediately (loud) rather than masking a persistent
+ * connectivity fault behind silent retries.
+ */
+export declare function isTransientServerError(err: unknown): boolean;
+/**
+ * Execute a function with bounded retry on 429 rate-limit AND 5xx server
+ * errors, each with its own budget and exponential backoff (1s, 2s, …).
+ * Every other error — a 4xx, or a network error with no `status` — is
+ * rethrown immediately (loud; not retried).
  */
 export declare function withRateLimitRetry<T>(fn: () => Promise<T>, context: string): Promise<T>;
 /**
@@ -27,7 +35,7 @@ export declare function withRateLimitRetry<T>(fn: () => Promise<T>, context: str
  */
 export declare class GitHubChangedFilesFetcher implements ChangedFilesFetcher {
     private readonly config;
-    readonly provider: "github";
+    readonly provider: 'github';
     constructor(config: GitHubAppConfig);
     /**
      * Get changed files for a GitHub webhook event.
@@ -38,7 +46,7 @@ export declare class GitHubChangedFilesFetcher implements ChangedFilesFetcher {
      * @param credentials - Must be GitHubCredentials with installationId
      * @returns Array of changed file paths
      */
-    getChangedFiles(repoIdentifier: string, eventType: string, payload: unknown, credentials: unknown): Promise<string[]>;
+    getChangedFiles(repoIdentifier: string, eventType: string, payload: unknown, credentials: unknown): Promise<ChangedFilesResult>;
     /**
      * Get changed files for a pull request event using paginated listFiles API.
      */

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

@@ -2,10 +2,15 @@
  * GitHub implementation of the CheckStatusPoster interface.
  *
  * Posts check statuses to GitHub PRs using the Checks API for:
- * - Security holds (pending): "KiCI Security: Held for approval"
- * - Workflow modifications (neutral): "KiCI: Workflow changes detected"
+ * - 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"
  * - 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.
+ *
  * Reuses the Octokit infrastructure from auth.ts via createInstallationOctokit.
  * Uses a fixed check name per category so that subsequent updates (approve/reject)
  * can find and update the existing check run.
@@ -21,7 +26,7 @@ import type { WorkflowModification } from '../../security/workflow-diff.js';
  */
 export declare class GitHubCheckStatusPoster implements CheckStatusPoster {
     private readonly getOctokit;
-    readonly provider: "github";
+    readonly provider: 'github';
     constructor(getOctokit: (credentials: unknown) => Octokit);
     postCheckStatus(repoIdentifier: string, commitSha: string, status: CheckStatus, title: string, summary: string, credentials: unknown): Promise<void>;
     /**
@@ -31,5 +36,16 @@ export declare class GitHubCheckStatusPoster implements CheckStatusPoster {
      * conflict with the security hold check. Always posted as neutral/completed.
      */
     postWorkflowModificationCheck(repoIdentifier: string, commitSha: string, modifications: WorkflowModification[], credentials: unknown): Promise<void>;
+    /**
+     * Post the informational check recording that the org's global workflows were
+     * skipped because the trust policy held or rejected the event.
+     *
+     * Uses a separate check name ("KiCI: Organization workflows") so it never
+     * overwrites the security-hold check: that one is a single named run per
+     * commit which the hold posts as pending and approve / reject later complete,
+     * so writing this notice onto it would resolve the hold's check to neutral
+     * while the run is still held. Always posted as neutral/completed.
+     */
+    postGlobalWorkflowsSkippedCheck(repoIdentifier: string, commitSha: string, summary: string, credentials: unknown): Promise<void>;
 }
 //# sourceMappingURL=check-status-poster.d.ts.map

package/dist/providers/github/contributor-resolver.d.ts

@@ -15,7 +15,7 @@ import { type GitHubAppConfig } from './auth.js';
  */
 export declare class GitHubContributorResolver implements ContributorResolver {
     private readonly config;
-    readonly provider: "github";
+    readonly provider: 'github';
     constructor(config: GitHubAppConfig);
     /**
      * Resolve a contributor's permission level on a GitHub repository.

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

@@ -17,7 +17,7 @@ import { type GitHubAppConfig } from './auth.js';
  */
 export declare class GitHubLockFileFetcher implements LockFileFetcher {
     private readonly config;
-    readonly provider: "github";
+    readonly provider: 'github';
     constructor(config: GitHubAppConfig);
     /**
      * Fetch the lock file from a GitHub repository at a specific ref.

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

@@ -12,7 +12,7 @@ import type { WebhookNormalizer, SimulatedEvent, AccessCacheInvalidation } from
  * Headers are expected lowercase (Hono normalizes them).
  */
 export declare class GitHubWebhookNormalizer implements WebhookNormalizer {
-    readonly provider: "github";
+    readonly provider: 'github';
     /**
      * Extract routing key from GitHub webhook headers.
      *

package/dist/providers/github/repo-url.d.ts

@@ -12,7 +12,7 @@ import type { RepoUrlBuilder } from '@kici-dev/engine';
  * repoIdentifier is expected in "owner/repo" format.
  */
 export declare class GitHubRepoUrlBuilder implements RepoUrlBuilder {
-    readonly provider: "github";
+    readonly provider: 'github';
     /**
      * Build the HTTPS clone URL for a GitHub repository.
      *

package/dist/providers/local/lock-file-fetcher.d.ts

@@ -14,7 +14,7 @@ import type { LockFileFetcher, LockFile } from '@kici-dev/engine';
  */
 export declare class LocalLockFileFetcher implements LockFileFetcher {
     private readonly repoBasePath;
-    readonly provider: "local";
+    readonly provider: 'local';
     /**
      * @param repoBasePath - Base directory for the repo(s). When repoIdentifier
      *   starts with 'file://', it is stripped and used as-is. Otherwise

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

@@ -17,7 +17,7 @@ import type { WebhookNormalizer, SimulatedEvent, AccessCacheInvalidation } from
  * (e.g., {ref: 'refs/heads/master', repository: {full_name: 'test/repo'}}).
  */
 export declare class LocalWebhookNormalizer implements WebhookNormalizer {
-    readonly provider: "local";
+    readonly provider: 'local';
     /**
      * Extract routing key from the local-source webhook headers.
      *

package/dist/providers/local/repo-url-builder.d.ts

@@ -16,7 +16,7 @@ import type { RepoUrlBuilder } from '@kici-dev/engine';
 export declare class LocalRepoUrlBuilder implements RepoUrlBuilder {
     private readonly repoBasePath;
     private readonly cloneUrlBase?;
-    readonly provider: "local";
+    readonly provider: 'local';
     /**
      * @param repoBasePath - Base directory where test repos live on disk
      * @param cloneUrlBase - Optional URL base for clone operations (e.g. git://host/path).

package/dist/providers/universal-git/changed-files.d.ts

@@ -8,12 +8,13 @@
  * `commits[].{added,modified,removed}` arrays in the push payload, so we
  * extract them via JSONPath from the already-delivered webhook body.
  *
- * For PR events we return an empty list: the upstream trigger matcher treats
- * empty changed-files as "match any path", which is the safest default when
- * we don't have per-PR diff data. A follow-up can add an optional REST
- * fetcher if source authors want PR path filtering.
+ * For PR events we report `unavailable`: no per-commit diff is present in the
+ * webhook body, so the upstream trigger matcher matches path filters
+ * conservatively (the workflow runs) instead of silently never matching. A
+ * follow-up can add an optional REST fetcher if source authors want exact PR
+ * path filtering.
  */
-import type { ChangedFilesFetcher } from '@kici-dev/engine';
+import type { ChangedFilesFetcher, ChangedFilesResult } from '@kici-dev/engine';
 import { type UniversalGitConfig } from './config.js';
 /**
  * Universal-git implementation of ChangedFilesFetcher.
@@ -22,7 +23,7 @@ import { type UniversalGitConfig } from './config.js';
  * expanded `payloadPaths` + `eventMapping`.
  */
 export declare class UniversalGitChangedFilesFetcher implements ChangedFilesFetcher {
-    readonly provider: "generic";
+    readonly provider: 'generic';
     private readonly paths;
     private readonly eventMapping;
     constructor(params: {
@@ -36,7 +37,7 @@ export declare class UniversalGitChangedFilesFetcher implements ChangedFilesFetc
      * @param payload         The webhook body the forge delivered.
      * @param _credentials    Unused — no REST call is made.
      */
-    getChangedFiles(_repoIdentifier: string, eventType: string, payload: unknown, _credentials: unknown): Promise<string[]>;
+    getChangedFiles(_repoIdentifier: string, eventType: string, payload: unknown, _credentials: unknown): Promise<ChangedFilesResult>;
     private classifyEvent;
 }
 //# sourceMappingURL=changed-files.d.ts.map

package/dist/providers/universal-git/clone-token.d.ts

@@ -42,7 +42,7 @@ export interface UniversalGitAuth extends ProviderGitAuth {
  */
 export declare class UniversalGitCloneTokenProvider implements CloneTokenProvider {
     private readonly params;
-    readonly provider: "generic";
+    readonly provider: 'generic';
     constructor(params: {
         orgId: string;
         sourceId: string;

package/dist/providers/universal-git/config.d.ts

@@ -22,9 +22,9 @@ export declare const UniversalGitPreset: z.ZodEnum<{
     custom: "custom";
     forgejo: "forgejo";
     gitea: "gitea";
-    gogs: "gogs";
-    "gitlab-repo": "gitlab-repo";
     "github-repo": "github-repo";
+    "gitlab-repo": "gitlab-repo";
+    gogs: "gogs";
 }>;
 export type UniversalGitPreset = z.infer<typeof UniversalGitPreset>;
 /**
@@ -101,9 +101,9 @@ export declare const UniversalGitConfigSchema: z.ZodObject<{
         custom: "custom";
         forgejo: "forgejo";
         gitea: "gitea";
-        gogs: "gogs";
-        "gitlab-repo": "gitlab-repo";
         "github-repo": "github-repo";
+        "gitlab-repo": "gitlab-repo";
+        gogs: "gogs";
     }>;
     gitUrlTemplate: z.ZodString;
     credentialRef: z.ZodObject<{

package/dist/providers/universal-git/index.d.ts

@@ -24,6 +24,7 @@
 import type { ProviderBundle } from '../../provider-registry.js';
 import type { GenericWebhookSource } from '../../db/types.js';
 import type { SecretResolver } from '../../secrets/secret-resolver.js';
+import type { ClusterSettingsReader } from '../../cluster/cluster-settings-reader.js';
 import { type UniversalGitConfig } from './config.js';
 export { UniversalGitWebhookNormalizer } from './normalizer.js';
 export { UniversalGitLockFileFetcher, LockFileTooLargeError } from './lock-file.js';
@@ -51,5 +52,8 @@ export declare function parseSourceGitConfig(raw: string | Record<string, unknow
  * generic webhook, not a universal-git source) — callers can rely on this
  * to differentiate the two shapes without re-parsing the row.
  */
-export declare function createUniversalGitProviderBundle(source: Pick<GenericWebhookSource, 'id' | 'customer_id' | 'routing_key' | 'git_config'>, secretResolver: SecretResolver): ProviderBundle | null;
+export declare function createUniversalGitProviderBundle(source: Pick<GenericWebhookSource, 'id' | 'customer_id' | 'routing_key' | 'git_config'>, secretResolver: SecretResolver, opts?: {
+    clusterSettings?: ClusterSettingsReader;
+    lockFileMaxBytes?: number;
+}): ProviderBundle | null;
 //# sourceMappingURL=index.d.ts.map

package/dist/providers/universal-git/lock-file.d.ts

@@ -30,6 +30,7 @@
  */
 import type { LockFileFetcher, LockFile } from '@kici-dev/engine';
 import type { SecretResolver } from '../../secrets/secret-resolver.js';
+import type { ClusterSettingsReader } from '../../cluster/cluster-settings-reader.js';
 import type { UniversalGitConfig } from './config.js';
 /**
  * Typed error for the 5 MiB cap. Callers can differentiate this from
@@ -49,13 +50,17 @@ export declare class LockFileTooLargeError extends Error {
  */
 export declare class UniversalGitLockFileFetcher implements LockFileFetcher {
     private readonly params;
-    readonly provider: "generic";
+    readonly provider: 'generic';
     private readonly repoUrlBuilder;
     constructor(params: {
         orgId: string;
         sourceId: string;
         config: UniversalGitConfig;
         secretResolver: SecretResolver;
+        /** Fleet-wide settings reader; overrides the lock-file cap per fetch. */
+        clusterSettings?: ClusterSettingsReader;
+        /** Cluster default cap (bytes) when no cluster_settings override is set. */
+        lockFileMaxBytes?: number;
     });
     /**
      * Shallow-clone the source repo at `ref` into a private tempdir, read

package/dist/providers/universal-git/normalizer.d.ts

@@ -22,7 +22,7 @@ import { type UniversalGitConfig } from './config.js';
  * registered `generic_webhook_sources` row with a non-null `git_config`.
  */
 export declare class UniversalGitWebhookNormalizer implements WebhookNormalizer {
-    readonly provider: "generic";
+    readonly provider: 'generic';
     private readonly routingKey;
     private readonly paths;
     private readonly eventMapping;

package/dist/providers/universal-git/repo-url.d.ts

@@ -18,7 +18,7 @@ import type { RepoUrlBuilder } from '@kici-dev/engine';
  */
 export declare class UniversalGitRepoUrlBuilder implements RepoUrlBuilder {
     private readonly gitUrlTemplate;
-    readonly provider: "generic";
+    readonly provider: 'generic';
     constructor(gitUrlTemplate: string);
     /**
      * Build the clone URL by substituting placeholders in the template with

package/dist/queue/cleanup.d.ts

@@ -1,7 +1,71 @@
 import { type Kysely } from 'kysely';
+import { type LabelMatcher } from '@kici-dev/engine';
 import type { Database } from '../db/types.js';
 import type { ExecutionTracker } from '../reporting/execution-tracker.js';
+import type { CheckRunReporter } from '../reporting/check-run-reporter.js';
+import type { CheckRunTrackingStore } from '../reporting/check-run-tracking-store.js';
+import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
+import type { LogStorage } from '../reporting/log-storage.js';
 import { JobQueue } from './job-queue.js';
+/**
+ * Optional cleanup dependencies + retention knobs. Present in platform/hybrid
+ * mode (the only wiring site, `orchestrator-core`, always supplies them); the
+ * retention sweeps and Platform status-forwarding run only when this is set.
+ */
+export interface CleanupExtras {
+    db: Kysely<Database>;
+    executionTracker: ExecutionTracker;
+    /**
+     * Resolves each expired job's check run to a terminal conclusion.
+     *
+     * Required for correctness, not decoration: this sweep settles a job by
+     * writing `execution_jobs` directly rather than through
+     * `ExecutionTracker.onJobStatus`, so the tracker's terminal-job hook — the
+     * funnel a tracker-driven terminal status reaches the check-run reporter
+     * through — never fires here. Absent, the check run created at trigger match
+     * stays `queued` on the commit forever, which no branch-protection rule
+     * requiring it can ever be satisfied by.
+     */
+    checkRunReporter?: Pick<CheckRunReporter, 'updateJobStatus'>;
+    /** Terminal dispatch_queue row retention (days); 0 disables. Default 30. */
+    dispatchQueueTtlDays?: number;
+    /** Step-log object retention (days); 0 disables. Default 90. */
+    stepLogTtlDays?: number;
+    /** Store for `check_run_tracking`; the retention sweep runs only when wired. */
+    checkRunTrackingStore?: CheckRunTrackingStore;
+    /** Live cluster-settings reader; absent ⇒ the config default is used as-is. */
+    clusterSettings?: ClusterSettingsReader;
+    /** `check_run_tracking` row retention (days); 0 disables. Default 7. */
+    checkRunTrackingTtlDays?: number;
+    /** The orchestrator's log storage — the S3 sweep runs only when S3-backed. */
+    logStorage?: LogStorage;
+    /** True when `logStorage` is the S3 backend (the filesystem backend is
+     *  customer-managed, so its lifecycle stays the operator's concern). */
+    logStorageIsS3?: boolean;
+    /**
+     * Whether ANYTHING could ever have run a job with these selectors — a
+     * registered agent (regardless of capacity) or a scaler backend able to spawn
+     * one.
+     *
+     * Read once per expired job to split the two reasons a queued job never ran:
+     * nothing in the fleet matched its `runsOn` (`unroutable` — a label/fleet
+     * problem an operator has to fix) versus something matched but never produced
+     * a usable agent (`timed_out_stale` — a capacity or provisioning problem).
+     * Both halves are load-bearing: a scaler-managed pool at zero has no
+     * registered agent yet still routes perfectly well, so asking only the agent
+     * registry would report every failed spawn as a bad `runsOn`.
+     *
+     * Asked at expiry rather than at dispatch so a label satisfied moments later
+     * by an autoscaled agent is not mislabelled unroutable. Absent → every expiry
+     * stays `timed_out_stale`, the behaviour before the split existed.
+     *
+     * The predicate is allowed to answer "routable" conservatively (the scaler
+     * half matches exact labels only, so a pattern-only `runsOn` reads routable on
+     * a scaler-configured orchestrator). That costs precision on the status, never
+     * safety: the job is terminal either way and the run fails either way.
+     */
+    canRouteLabels?: (requiredLabels: string[], requiredPatterns: LabelMatcher[], excludeLabels: string[], excludePatterns: LabelMatcher[]) => boolean;
+}
 /**
  * Run a single cleanup pass: remove expired dedup_cache entries and
  * mark expired dispatch_queue entries.
@@ -18,12 +82,12 @@ import { JobQueue } from './job-queue.js';
  */
 export declare function runCleanup(dedup: {
     cleanup(): Promise<number>;
-}, queue: JobQueue, extras?: {
-    db: Kysely<Database>;
-    executionTracker: ExecutionTracker;
-}): Promise<{
+}, queue: JobQueue, extras?: CleanupExtras): Promise<{
     dedupDeleted: number;
     queueExpired: number;
+    dispatchRowsPruned: number;
+    logObjectsPruned: number;
+    checkRunRowsPruned: number;
 }>;
 /**
  * Build a per-tick handler for the queue-cleanup scheduled job.
@@ -34,8 +98,5 @@ export declare function runCleanup(dedup: {
  */
 export declare function createCleanupHandler(dedup: {
     cleanup(): Promise<number>;
-}, queue: JobQueue, extras?: {
-    db: Kysely<Database>;
-    executionTracker: ExecutionTracker;
-}): () => Promise<void>;
+}, queue: JobQueue, extras?: CleanupExtras): () => Promise<void>;
 //# sourceMappingURL=cleanup.d.ts.map