@kici-dev/orchestrator 0.5.0 → 0.6.0

package/dist/stale-detector/gate-deadline-detector.d.ts

@@ -0,0 +1,52 @@
+/**
+ * GateDeadlineDetector: periodic DB scanner enforcing an invoke gate's own
+ * job-level `timeout`.
+ *
+ * A gate runs no steps on an agent, so the agent-side job timeout can never fire
+ * for it. Instead the orchestrator owns the gate deadline: this scanner finds
+ * non-terminal `gate` jobs whose `timeout_ms` has elapsed since the gate began
+ * summoning and fails each one. Failing the gate drives its downstream `needs`
+ * cascade through the normal job-status path; the summoned source-repo runs are
+ * the repos' own runs and are left untouched.
+ *
+ * The gate's timeout clock is `ready_at` (when the needs scheduler released it to
+ * summon), falling back to `created_at` for a root gate that never carried a
+ * `ready_at`.
+ */
+import { type Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { ExecutionTracker } from '../reporting/execution-tracker.js';
+/**
+ * Recency window for the deadline-bounded scan, mirroring the workflow deadline
+ * detector: a gate stays in scope while its deadline lapsed within this window,
+ * which keeps long-timeout gates enforced while skipping ancient history.
+ */
+export declare const GATE_DEADLINE_RECENCY_WINDOW_MS: number;
+export interface GateDeadlineDetectorDeps {
+    db: Kysely<Database>;
+    /** Used to fail an overdue gate through the canonical job-status path. */
+    executionTracker: Pick<ExecutionTracker, 'onJobStatus'>;
+    /** How often to scan in ms (reuses the stale-detector interval). */
+    scanIntervalMs: number;
+}
+export declare class GateDeadlineDetector {
+    private readonly db;
+    private readonly executionTracker;
+    private readonly scanIntervalMs;
+    private interval;
+    constructor(deps: GateDeadlineDetectorDeps);
+    /** Start the detector: an immediate crash-recovery scan, then periodic scans. */
+    start(): Promise<void>;
+    stop(): void;
+    /** Find non-terminal gates past their timeout and fail each one. */
+    scan(): Promise<void>;
+    /**
+     * Build the SELECT for overdue gates. Extracted so a unit test can compile the
+     * exact predicate set (Kysely `.compile()`) without a live database. A gate is
+     * overdue when `coalesce(ready_at, created_at) + timeout_ms` is in the past;
+     * the recency bound keeps the scan off ancient history each tick.
+     */
+    private buildOverdueQuery;
+    private failOverdueGate;
+}
+//# sourceMappingURL=gate-deadline-detector.d.ts.map

package/dist/stale-detector/stale-run-detector.d.ts

@@ -22,6 +22,7 @@ import type { CheckRunReporter } from '../reporting/check-run-reporter.js';
 import type { ScalerManager } from '../scaler/manager.js';
 import type { Dispatcher } from '../agent/dispatcher.js';
 import type { AgentRegistry } from '../agent/registry.js';
+import { type ResolveCheckStatusPoster } from '../pipeline/security-hold-check.js';
 import type { HeldRunStore, ReleaseSignal } from '../contexts/held-runs.js';
 import type { StepApprovalBridge } from '../approvals/step-approval-bridge.js';
 import type { AccessLogWriter } from '../audit/access-log.js';
@@ -60,8 +61,32 @@ export interface StaleRunDetectorDeps {
      * set, wait-timer workflow holds are not auto-released.
      */
     onWorkflowRelease?: (signal: ReleaseSignal) => Promise<void>;
+    /**
+     * Resume a released JOB-scoped hold by re-dispatching the job. A job-scoped
+     * wait-timer hold has a pending job context, not a pending workflow context,
+     * so it cannot go through `onWorkflowRelease`.
+     */
+    onJobRelease?: (signal: ReleaseSignal) => Promise<void>;
+    /**
+     * Resolve a context by name, for the queued-concurrency sweep — it needs each
+     * group's configured `concurrency_limit` to know how many holds a freed slot
+     * lets through. `ContextStore.matchContext`.
+     */
+    matchContext?: (orgId: string, name: string) => Promise<{
+        concurrency_limit: number | null;
+    } | null>;
     /** Access-log writer for the orchestrator audit stream. Optional -- if not set, expiry audit rows (`held_run.expire`) are skipped. */
     accessLogWriter?: AccessLogWriter;
+    /**
+     * Resolve the check poster of the provider bundle serving a routing key, so an
+     * expiring security hold's `KiCI Security` check can be completed. A function
+     * rather than the registry itself because the registry instance is replaced
+     * when sources are (re)loaded, and this detector outlives that.
+     *
+     * Optional -- if not set, an expiring security hold's check is left alone,
+     * which is the pre-existing behaviour rather than a wrong one.
+     */
+    resolveCheckStatusPoster?: ResolveCheckStatusPoster;
 }
 export declare class StaleRunDetector {
     private readonly db;
@@ -79,13 +104,38 @@ export declare class StaleRunDetector {
     private readonly stepApprovalBridge?;
     private readonly failRun?;
     private readonly onWorkflowRelease?;
+    private readonly onJobRelease?;
+    private readonly matchContext?;
     private readonly accessLogWriter?;
+    private readonly resolveCheckStatusPoster?;
     private interval;
     constructor(deps: StaleRunDetectorDeps);
     /**
-     * Release workflow install-gate wait-timer holds whose timer has elapsed.
-     * Runs BEFORE `expireOverdueHolds` so a wait hold resumes the workflow rather
-     * than being failed by the expire-and-fail sweep.
+     * Release queued concurrency holds whose group now has a free slot.
+     *
+     * A context's concurrency gate returns `queue` when its limit is met, holding
+     * the job. Nothing released those holds: they sat pending until the expiry
+     * sweep marked them expired and their jobs never ran. This is the release
+     * half.
+     *
+     * Driven from the periodic scan rather than from job completion: the
+     * completion callback is constructed before the dispatcher, coordinator and
+     * context store exist, so wiring it there would mean threading four refs
+     * through a hot path. The cost is up to one scan interval of latency before a
+     * freed slot is reused, which for a throughput control is an acceptable
+     * trade — and every release still re-checks the limit, so the bound is never
+     * exceeded regardless of when the sweep runs.
+     */
+    private releaseFreedConcurrencyHolds;
+    /**
+     * Release wait-timer holds whose timer has elapsed, at ANY scope, and route
+     * each to the resume path its shape requires: a workflow install-gate hold
+     * rebuilds its workflow dispatch context, a job-scoped hold re-dispatches the
+     * one job it held.
+     *
+     * Runs BEFORE `expireOverdueHolds` so a wait hold resumes rather than being
+     * failed by the expire-and-fail sweep — that sweep is not scope-filtered, so
+     * the ordering is load-bearing.
      */
     private releaseDueWaitHolds;
     /**
@@ -93,6 +143,14 @@ export declare class StaleRunDetector {
      * bulk status flip: step-scoped holds notify the waiting agent (which fails
      * the step), job/workflow-scoped holds fail the whole run. Then the bulk
      * `expireOverdue()` flips every overdue row to `expired`.
+     *
+     * Every overdue row's id is excluded from the security check's contention
+     * query for the whole loop, because `expireOverdue()` has not run yet: each
+     * of them is still `pending` in the database while its siblings are being
+     * routed, and without the exclusion a commit whose two holds both expired
+     * would see each hold refuse on account of the other and leave the check
+     * pending forever. The commits already settled are tracked so one sweep
+     * writes each shared check once.
      */
     private expireOverdueHolds;
     /**