@kici-dev/orchestrator 0.1.26 → 0.2.0

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

@@ -29,5 +29,6 @@ export { LocalRepoUrlBuilder } from './repo-url-builder.js';
 export declare function createLocalProviderBundle(opts: {
     repoBasePath: string;
     cloneUrlBase?: string;
+    inPlace?: boolean;
 }): ProviderBundle;
 //# sourceMappingURL=index.d.ts.map

package/dist/providers/local/local-source-config.d.ts

@@ -12,6 +12,7 @@ import { z } from 'zod';
 export declare const LocalSourceConfigSchema: z.ZodObject<{
     repoBasePath: z.ZodString;
     cloneUrlBase: z.ZodOptional<z.ZodString>;
+    inPlace: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type LocalSourceConfig = z.infer<typeof LocalSourceConfigSchema>;
 //# sourceMappingURL=local-source-config.d.ts.map

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

package/dist/queue/job-queue.d.ts

@@ -1,6 +1,7 @@
 import { type Kysely } from 'kysely';
 import { type LabelMatcher, type ResourceRequest } from '@kici-dev/engine';
 import type { Database } from '../db/types.js';
+import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 /** Info about an expired dispatch_queue entry, returned by markExpired(). */
 export interface ExpiredJobInfo {
     /** dispatch_queue row ID */
@@ -9,6 +10,16 @@ export interface ExpiredJobInfo {
     jobName: string;
     /** Most recent scaler spawn-failure detail, if any was recorded. */
     lastProvisioningError: string | null;
+    /**
+     * The job's routing selectors, carried so the expiry sweep can ask whether
+     * any agent could ever have run it. A job that expires with NO matching agent
+     * is `unroutable` (a fleet/label problem); one whose agent existed but never
+     * freed up is `timed_out_stale` (a capacity problem).
+     */
+    runsOnLabels: string[];
+    runsOnPatterns: LabelMatcher[];
+    excludeLabels: string[];
+    excludePatterns: LabelMatcher[];
 }
 /**
  * Point-in-time breakdown of dispatch_queue depth used for Prometheus gauges
@@ -167,8 +178,12 @@ export interface QueuedJob {
  */
 export declare class JobQueue {
     private readonly db;
-    private readonly maxDepth;
+    /** Cluster-wide fallback for queue_max_depth when cluster_settings is null. */
+    private readonly defaultMaxDepth;
     private readonly defaultTimeoutMs;
+    private readonly clusterSettings?;
+    /** Per-job (per-org) queue-timeout resolver; falls back to defaultTimeoutMs. */
+    private readonly getQueueTimeoutMs?;
     /** 1-second TTL cache for pending depth count to avoid extra SELECT COUNT per enqueue. */
     private depthCache;
     /**
@@ -181,9 +196,16 @@ export declare class JobQueue {
     constructor(db: Kysely<Database>, options: {
         maxDepth: number;
         defaultTimeoutMs: number;
+        clusterSettings?: ClusterSettingsReader;
+        getQueueTimeoutMs?: (job: {
+            jobConfig?: Record<string, unknown>;
+        }) => Promise<number>;
     });
     /**
-     * Enqueue a job. Checks depth first, rejects with 'queue full' if >= maxDepth.
+     * Enqueue a job. Checks depth first, rejects with 'queue full' if >= the
+     * fleet-wide `queue_max_depth` (cluster_settings, falling back to the config
+     * default). The per-job timeout resolves through the per-org
+     * `queue_timeout_ms` override.
      * @returns The generated job ID.
      */
     enqueue(job: QueuedJobInput): Promise<string>;
@@ -269,17 +291,38 @@ export declare class JobQueue {
     /**
      * Insert a job directly with status='dispatched' (bypasses the queue).
      * Used when an agent is immediately available and the job doesn't need to wait.
-     * @returns The generated job ID.
+     *
+     * `agentId` is the durable owner, written here for the same reason
+     * {@link markDispatched} writes it on the queue-drain path: this row is
+     * dispatched the moment it is inserted, so it never passes through
+     * `markDispatched` and would otherwise carry a NULL owner for its whole life.
+     * A coordinator that never saw the dispatch resolves ownership from this
+     * column alone, so omitting it here would make {@link hasAgentOwnedJob} answer
+     * "not owned" for every directly-dispatched job after a failover.
+     *
+     * Idempotent on the primary key: a reroute re-dispatch reuses a preassigned
+     * jobId, so a concurrent reroute from a sibling coordinator (or a duplicate
+     * delivery) may target a row this instance already wrote. ON CONFLICT (id) DO
+     * NOTHING makes that a no-op instead of a dispatch_queue_pkey error; the
+     * returned `inserted` flag tells the caller whether a fresh row was created so
+     * it can avoid double-dispatching an already-present job. The conflicting row
+     * keeps the owner the winning writer recorded.
+     *
+     * @returns The job ID and whether a new row was inserted (false = row already existed).
      */
-    insertDispatched(job: QueuedJobInput): Promise<string>;
+    insertDispatched(job: QueuedJobInput, agentId: string): Promise<{
+        id: string;
+        inserted: boolean;
+    }>;
     /**
-     * Mark a job as dispatched.
+     * Mark a job as dispatched and record the agent it went to.
      *
-     * Note: agentId is not persisted in the dispatch_queue table.
-     * The dispatcher tracks agent-to-job mappings in memory (agentJobs Map).
-     * The dispatch_queue is a transient routing table, not the execution record.
+     * `agent_id` is the durable owner: the dispatcher also tracks agent-to-job
+     * mappings in memory (agentJobs Map), but that map is per-coordinator, so a
+     * coordinator that never saw the dispatch has to read the owner back from the
+     * row to answer an ownership question.
      */
-    markDispatched(jobId: string, _agentId: string): Promise<void>;
+    markDispatched(jobId: string, agentId: string): Promise<void>;
     /**
      * Mark a job as failed.
      *
@@ -329,6 +372,23 @@ export declare class JobQueue {
      * @returns Number of affected rows.
      */
     cancelByRunId(runId: string): Promise<number>;
+    /**
+     * Delete terminal dispatch_queue rows older than `retentionDays`.
+     *
+     * `dispatch_queue` is operational dispatch state; the durable run history
+     * lives in the cold-stored execution_runs/jobs/steps tables, so a terminal
+     * ({@link DispatchQueueStatus.Completed}/{@link DispatchQueueStatus.Failed}/
+     * {@link DispatchQueueStatus.Expired}) row has no archival value once it ages
+     * out. Non-terminal rows ({@link DispatchQueueStatus.Pending}/
+     * {@link DispatchQueueStatus.Dispatched}/{@link DispatchQueueStatus.Recovering})
+     * are never pruned — a still-active run keeps every one of its rows. Both the
+     * terminal-status filter and the age cutoff must hold for a row to be deleted.
+     *
+     * `retentionDays <= 0` disables pruning (returns 0 without a query).
+     *
+     * @returns Number of rows deleted.
+     */
+    pruneTerminalDispatchRows(retentionDays: number): Promise<number>;
     /**
      * Get the current number of pending jobs.
      * Uses a 1-second TTL cache to avoid extra SELECT COUNT per enqueue.
@@ -455,11 +515,12 @@ export declare class JobQueue {
      */
     getFullJobById(jobId: string): Promise<QueuedJob | null>;
     /**
-     * Mark a job as dispatched only if it is still in 'recovering' state.
+     * Mark a job as dispatched only if it is still in 'recovering' state, and
+     * record `agentId` as the durable owner of the reclaimed job.
      * Used when an agent reconnects and claims a recovering job.
      * @returns true if the update affected a row (job was still recovering).
      */
-    markDispatchedIfRecovering(jobId: string): Promise<boolean>;
+    markDispatchedIfRecovering(jobId: string, agentId: string): Promise<boolean>;
     /**
      * Get a single job by ID.
      * Used to look up runId during recovery timer setup.
@@ -471,10 +532,11 @@ export declare class JobQueue {
     } | null>;
     /**
      * HA-safe ownership check. Returns true if the DB shows that
-     * `agentId` previously held `jobId` according to any of:
+     * `agentId` holds or previously held `jobId` according to any of:
      *
-     *   - `status='dispatched'` AND the registry-managed bookkeeping
-     *     records the agent assignment (caller-side `agentJobs` map),
+     *   - `status='dispatched'` AND `agent_id = <agent>` — the live
+     *     owner of an in-flight job, readable by any coordinator
+     *     including one that never saw the dispatch,
      *   - `status='recovering'` AND `recovery_agent_id = <agent>` (so a
      *     replacement coord still recognises in-flight chunks), OR
      *   - the row is already terminal (`completed` / `failed` /
@@ -495,11 +557,29 @@ export declare class JobQueue {
         id: string;
         runId: string;
         status: DispatchQueueStatus;
+        agentId: string | null;
     }>>;
+    /**
+     * Shared builder for the non-expired pending rows, oldest-first
+     * (`created_at ASC` — the same FIFO ordering as `dequeueForLabels` /
+     * `markExpired`). Read-only: no `FOR UPDATE`, no claim. Used by both the
+     * unbounded `getPendingJobs` drain and the capped `listPending` re-drive.
+     */
+    private pendingOldestFirstQuery;
     /**
      * Get all pending jobs in FIFO order (for queue drain on agent connect).
      */
     getPendingJobs(): Promise<QueuedJob[]>;
+    /**
+     * Read-only oldest-first listing of pending jobs, capped at `limit`.
+     *
+     * Powers the scaler capacity-freed re-drive (`Dispatcher.retryPendingScaleRequests`):
+     * when a scaler agent frees capacity, the oldest jobs that previously got an
+     * `at-capacity` verdict are the ones re-offered to `requestScale`. Unlike
+     * `dequeueForLabels`, this neither claims nor locks rows — it is a pure read;
+     * the re-drive re-runs the normal scale path, which reserves capacity itself.
+     */
+    listPending(limit: number): Promise<QueuedJob[]>;
     /**
      * Convert a DB row to a QueuedJob object.
      * Handles both auto-parsed JSONB arrays (from pg driver) and JSON strings (from tests).

package/dist/queue/scheduled-job.d.ts

@@ -25,10 +25,10 @@ import type { Database } from '../db/types.js';
  */
 export declare const OrchestratorScheduledJobName: z.ZodEnum<{
     cleanup: "cleanup";
-    "orphan-secret-cleanup": "orphan-secret-cleanup";
-    "token-cleanup": "token-cleanup";
     "cold-store-archive": "cold-store-archive";
     "cold-store-purge": "cold-store-purge";
+    "orphan-secret-cleanup": "orphan-secret-cleanup";
+    "token-cleanup": "token-cleanup";
 }>;
 export type OrchestratorScheduledJobName = z.infer<typeof OrchestratorScheduledJobName>;
 /** Access-log action for a manually triggered off-cadence tick. */

package/dist/registration/registration-index.d.ts

@@ -151,7 +151,7 @@ export declare class RegistrationIndex {
      *
      * Event type -> trigger type mapping:
      * - 'kici_event' -> 'kici_event'
-     * - 'workflow_complete' -> 'workflow_complete' or 'lifecycle'
+     * - 'workflow_complete' -> 'workflow_complete', 'lifecycle', or 'workflows_failed_batch'
      * - 'job_complete' -> 'job_complete' or 'lifecycle'
      * - 'generic_webhook' -> 'generic_webhook'
      * - 'schedule' -> 'schedule'