@kici-dev/orchestrator 0.2.0 → 0.4.0

package/dist/cluster/cluster-settings-reader.d.ts

@@ -1,7 +1,7 @@
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 /** Numeric columns on cluster_settings readable via {@link ClusterSettingsReader}. */
-export type ClusterNumberColumn = 'max_github_payload_bytes' | 'event_log_max_payload_bytes' | 'lock_file_max_bytes' | 'webhook_dedup_ttl_ms' | 'contributor_cache_ttl_ms' | 'event_router_event_ttl_seconds' | 'event_router_max_dispatch_attempts' | 'queue_max_depth' | 'reroute_flap_grace_ms' | 'max_fanout_hosts' | 'event_router_rate_limit_per_workflow_per_minute' | 'cache_max_tarball_bytes' | 'cache_ttl_days' | 'check_run_tracking_ttl_days' | 'concurrency_wait_timeout_ms' | 'agent_token_ttl_ms' | 'ownership_db_check_timeout_ms';
+export type ClusterNumberColumn = 'max_github_payload_bytes' | 'event_log_max_payload_bytes' | 'lock_file_max_bytes' | 'webhook_dedup_ttl_ms' | 'contributor_cache_ttl_ms' | 'event_router_event_ttl_seconds' | 'event_router_max_dispatch_attempts' | 'queue_max_depth' | 'reroute_flap_grace_ms' | 'max_fanout_hosts' | 'event_router_rate_limit_per_workflow_per_minute' | 'cache_max_tarball_bytes' | 'cache_ttl_days' | 'check_run_tracking_ttl_days' | 'concurrency_wait_timeout_ms' | 'agent_token_ttl_ms' | 'ownership_db_check_timeout_ms' | 'unroutable_grace_ms';
 /** Text columns on cluster_settings readable via {@link ClusterSettingsReader}. */
 export type ClusterStringColumn = 'dashboard_verified_issuer';
 /**

package/dist/config/schema.d.ts

@@ -164,6 +164,7 @@ export declare const appConfigSchema: z.ZodObject<{
     rosterTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueMaxDepth: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    unroutableGraceMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueBackpressureThreshold: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     lockfileCacheMax: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     lockfileCacheTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;

package/dist/config/types.d.ts

@@ -148,6 +148,8 @@ export interface AppConfig {
     /** Queue settings */
     queueMaxDepth: number;
     queueTimeoutMs: number;
+    /** Grace before a continuously-unroutable job is failed; 0 = disabled. */
+    unroutableGraceMs: number;
     /**
      * Pending-depth threshold for operator backpressure warnings. When the
      * pending dispatch_queue depth stays at or above this for two consecutive

package/dist/config.d.ts

@@ -58,6 +58,7 @@ declare const configSchema: z.ZodObject<{
     lockfileCacheMaxBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueMaxDepth: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    unroutableGraceMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueBackpressureThreshold: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     workerConcurrency: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     concurrencyWaitTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -251,6 +252,7 @@ export declare const packagingConfigSchema: z.ZodObject<{
     lockfileCacheMaxBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueMaxDepth: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    unroutableGraceMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueBackpressureThreshold: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     workerConcurrency: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     concurrencyWaitTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -477,6 +479,7 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     lockfileCacheMaxBytes: number;
     queueMaxDepth: number;
     queueTimeoutMs: number;
+    unroutableGraceMs: number;
     queueBackpressureThreshold: number;
     workerConcurrency: number;
     concurrencyWaitTimeoutMs: number;

package/dist/db/migrations/108_unroutable_fast_fail.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=108_unroutable_fast_fail.d.ts.map

package/dist/db/types.d.ts

@@ -274,6 +274,13 @@ export interface DispatchQueueTable {
      * real provisioning cause; cleared on dispatch. NULL when none recorded.
      */
     last_provisioning_error: ColumnType<string | null, string | null | undefined, string | null>;
+    /**
+     * When this job first read unroutable — no registered agent and no scaler
+     * backend matched its selectors. NULL once it reads routable again, so the
+     * grace clock only ever measures a CONTINUOUS unroutable window. Persisted
+     * rather than in-memory so a restart mid-grace resumes the same clock.
+     */
+    unroutable_since: ColumnType<Date | null, Date | string | null | undefined, Date | string | null>;
     /** Times this job was returned to pending for re-dispatch (job.reject / pre-start agent loss). */
     dispatch_attempts: Generated<number>;
     /**
@@ -518,6 +525,13 @@ export interface ExecutionJobTable {
     job_name: string;
     /** Job status: pending | running | success | failed | cancelled | skipped */
     status: Generated<string>;
+    /**
+     * Operator-facing reason this job cannot currently be routed to any agent.
+     * Written by the unroutable probe while the job is still queued, so the cause
+     * is visible long before the job terminalizes; cleared when a matching agent
+     * or scaler backend appears. NULL whenever the job is routable.
+     */
+    routing_reason: ColumnType<string | null, string | null | undefined, string | null>;
     /** Matrix values JSON (e.g. {"node": "18"}) */
     matrix_values: string | null;
     /** Agent ID that ran this job */
@@ -1702,6 +1716,12 @@ export interface ClusterSettingsTable {
      * NULL ⇒ the orchestrator's configured default.
      */
     check_run_tracking_ttl_days: ColumnType<number | null, number | null | undefined, number | null>;
+    /**
+     * Grace window (ms) a job may stay continuously unroutable before it is
+     * terminalized as `unroutable`. NULL = the orchestrator's configured default;
+     * 0 disables fast-fail, leaving `queue_timeout_ms` as the only backstop.
+     */
+    unroutable_grace_ms: ColumnType<number | null, number | null | undefined, number | null>;
     concurrency_wait_timeout_ms: ColumnType<string | null, number | null | undefined, number | null>;
     agent_token_ttl_ms: ColumnType<string | null, number | null | undefined, number | null>;
     /**

package/dist/index.js

@@ -2031,6 +2031,46 @@ function createTrustPolicyStoreFromUrl(databaseUrl, opts) {
 * All methods are thin wrappers around fetch() that handle JSON serialization,
 * error formatting, and URL construction.
 */
+/**
+* `fetch` rejects with a bare `TypeError: fetch failed` when it cannot reach the
+* host — it names neither the address dialled nor the knob that sets it. Printed
+* through the CLI's `Error: ${message}` handler that becomes `Error: fetch
+* failed`, which reads like a fault in the subcommand rather than a misaddressed
+* client, and sends the operator debugging the wrong thing.
+*
+* The trap is sharpened by two details of this CLI. The base URL comes from
+* `KICI_ADMIN_URL`, not the `KICI_ORCHESTRATOR_URL` an operator is likelier to
+* have exported; and subcommands accepting `--database-url` fall back to direct
+* DB access, so on a host with `KICI_DATABASE_URL` set they keep working while
+* the HTTP-only ones fail — making it look like specific subcommands are broken.
+*
+* So: name the address, name the variable, and name the near-miss.
+*/
+/**
+* Best-effort one-line detail from a rejected `fetch`. Returns '' when nothing
+* useful is available, so the caller can omit the parenthetical rather than
+* print an empty one.
+*/
+function firstCauseMessage(err) {
+	if (!(err instanceof Error)) return "";
+	const cause = err.cause;
+	if (!(cause instanceof Error)) return "";
+	if (cause.message) return cause.message;
+	const nested = cause.errors;
+	if (Array.isArray(nested)) {
+		for (const e of nested) if (e instanceof Error && e.message) return e.message;
+	}
+	return "";
+}
+async function fetchAdminApi(url, init, baseUrl) {
+	try {
+		return await fetch(url, init);
+	} catch (err) {
+		const detail = firstCauseMessage(err);
+		const cause = detail ? ` (${detail})` : "";
+		throw new Error(`cannot reach the orchestrator admin API at ${baseUrl}${cause}. Set KICI_ADMIN_URL to the orchestrator's HTTP address, or pass --base-url where the subcommand accepts it. Note KICI_ORCHESTRATOR_URL is NOT read by this CLI; if other subcommands appear to work, they are using the --database-url / KICI_DATABASE_URL direct-DB path rather than HTTP.`, { cause: err });
+	}
+}
 var AdminApiClient = class {
 	baseUrl;
 	token;
@@ -2042,16 +2082,14 @@ var AdminApiClient = class {
 	* Make an authenticated HTTP request to the admin API.
 	*/
 	async request(method, path, body) {
-		const url = `${this.baseUrl}${path}`;
-		const headers = {
-			Authorization: `Bearer ${this.token}`,
-			"Content-Type": "application/json"
-		};
-		const res = await fetch(url, {
+		const res = await fetchAdminApi(`${this.baseUrl}${path}`, {
 			method,
-			headers,
+			headers: {
+				Authorization: `Bearer ${this.token}`,
+				"Content-Type": "application/json"
+			},
 			body: body !== void 0 ? JSON.stringify(body) : void 0
-		});
+		}, this.baseUrl);
 		if (!res.ok) {
 			const text = await res.text();
 			let errorBody;
@@ -2099,11 +2137,10 @@ var AdminApiClient = class {
 	* Public GET request returning raw response text.
 	*/
 	async getText(path) {
-		const url = `${this.baseUrl}${path}`;
-		const res = await fetch(url, {
+		const res = await fetchAdminApi(`${this.baseUrl}${path}`, {
 			method: "GET",
 			headers: { Authorization: `Bearer ${this.token}` }
-		});
+		}, this.baseUrl);
 		if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
 		return res.text();
 	}
@@ -2116,14 +2153,14 @@ var AdminApiClient = class {
 	* response is an octet-stream, so it is read as bytes rather than parsed JSON.
 	*/
 	async downloadFleetBundle(body, outPath) {
-		const res = await fetch(`${this.baseUrl}/admin/fleet-bundle`, {
+		const res = await fetchAdminApi(`${this.baseUrl}/admin/fleet-bundle`, {
 			method: "POST",
 			headers: {
 				Authorization: `Bearer ${this.token}`,
 				"Content-Type": "application/json"
 			},
 			body: JSON.stringify(body)
-		});
+		}, this.baseUrl);
 		if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
 		const buf = Buffer.from(await res.arrayBuffer());
 		fs.writeFileSync(outPath, buf);

package/dist/metrics/prometheus.d.ts

@@ -404,6 +404,7 @@ export declare const installSecretsTokenResolutionDurationSeconds: import("@open
  * tick's `pruneTerminalDispatchRows`).
  */
 export declare const dispatchQueueRowsPrunedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+export declare const unroutableFastFailedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
  * Step-log objects deleted by the retention sweep (the cleanup tick's
  * `pruneExpiredLogs`, S3 backend only).

package/dist/queue/bootstrap.d.ts

@@ -29,6 +29,11 @@ export interface OrchestratorScheduledJobRegistrations {
         intervalMs: number;
         handler: () => Promise<void>;
     };
+    /** Short-tick probe that fast-fails jobs nothing in the fleet can route. */
+    unroutableProbe?: {
+        intervalMs: number;
+        handler: () => Promise<void>;
+    };
     orphanSecretCleanup?: {
         intervalMs: number;
         handler: () => Promise<void>;

package/dist/queue/cleanup.d.ts

@@ -1,5 +1,4 @@
-import { type Kysely } from 'kysely';
-import { type LabelMatcher } from '@kici-dev/engine';
+import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 import type { ExecutionTracker } from '../reporting/execution-tracker.js';
 import type { CheckRunReporter } from '../reporting/check-run-reporter.js';
@@ -7,6 +6,7 @@ import type { CheckRunTrackingStore } from '../reporting/check-run-tracking-stor
 import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 import type { LogStorage } from '../reporting/log-storage.js';
 import { JobQueue } from './job-queue.js';
+import { type CanRouteLabels } from './terminalize-unroutable.js';
 /**
  * Optional cleanup dependencies + retention knobs. Present in platform/hybrid
  * mode (the only wiring site, `orchestrator-core`, always supplies them); the
@@ -55,16 +55,18 @@ export interface CleanupExtras {
      * 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.
+     * Asked both on the unroutable probe's short tick (where a grace window
+     * absorbs a label satisfied moments later by an autoscaled agent) and again
+     * at expiry, which stays the backstop when fast-fail is disabled. 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;
+    canRouteLabels?: CanRouteLabels;
 }
 /**
  * Run a single cleanup pass: remove expired dedup_cache entries and

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

@@ -21,6 +21,14 @@ export interface ExpiredJobInfo {
     excludeLabels: string[];
     excludePatterns: LabelMatcher[];
 }
+/**
+ * A pending job as the unroutable probe sees it: the same routing facts the
+ * expiry sweep reads, plus the persisted grace clock.
+ */
+export interface UnroutableCandidate extends ExpiredJobInfo {
+    /** When this job first read unroutable; null while it reads routable. */
+    unroutableSince: Date | null;
+}
 /**
  * Point-in-time breakdown of dispatch_queue depth used for Prometheus gauges
  * and operator-facing depth warnings.
@@ -580,6 +588,45 @@ export declare class JobQueue {
      * the re-drive re-runs the normal scale path, which reserves capacity itself.
      */
     listPending(limit: number): Promise<QueuedJob[]>;
+    /**
+     * Pending, non-expired jobs with the facts the unroutable probe needs:
+     * routing selectors, any recorded provisioning error, and the grace clock.
+     *
+     * Read-only — no claim, no `FOR UPDATE`; the probe never dispatches. Reuses
+     * the shared pending query so it inherits the same FIFO ordering and
+     * not-yet-expired filter the rest of the queue uses.
+     */
+    listUnroutableCandidates(limit: number): Promise<UnroutableCandidate[]>;
+    /**
+     * Stamp the grace clock the first time a job reads unroutable.
+     *
+     * The `unroutable_since IS NULL` guard is load-bearing, not defensive: the
+     * cleanup/probe ticks are NOT leader-gated, so without it two coordinators
+     * would each re-stamp `now` on every tick, pushing the deadline outward
+     * forever and preventing the grace from ever elapsing.
+     */
+    markUnroutableSince(id: string, at: Date): Promise<void>;
+    /** Clear the grace clock after the job reads routable again. */
+    clearUnroutableState(id: string): Promise<void>;
+    /**
+     * Claim a still-pending row for fast-fail, moving it out of the queue.
+     *
+     * Mirrors {@link markExpired}: the queue row has to leave `Pending` in the
+     * same breath the job is terminalized, and for the same two reasons.
+     * A row left pending is still dispatchable, so an agent connecting later
+     * would pick up a job whose `execution_jobs` row already reads terminal; and
+     * the probe re-lists it on every tick, re-running the whole terminalize path
+     * (and re-counting the fast-fail metric) until the queue timeout finally
+     * expires it.
+     *
+     * The `status = Pending` guard is also the concurrency arbiter — probe ticks
+     * are NOT leader-gated, so exactly one coordinator's UPDATE hits a row and
+     * the losers get `false` and move on.
+     *
+     * @returns true when this call claimed the row, false when it was already
+     *   dispatched, cancelled, expired, or claimed by another coordinator.
+     */
+    claimUnroutable(id: string): Promise<boolean>;
     /**
      * 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

@@ -29,6 +29,7 @@ export declare const OrchestratorScheduledJobName: z.ZodEnum<{
     "cold-store-purge": "cold-store-purge";
     "orphan-secret-cleanup": "orphan-secret-cleanup";
     "token-cleanup": "token-cleanup";
+    "unroutable-probe": "unroutable-probe";
 }>;
 export type OrchestratorScheduledJobName = z.infer<typeof OrchestratorScheduledJobName>;
 /** Access-log action for a manually triggered off-cadence tick. */

package/dist/queue/terminalize-unroutable.d.ts

@@ -0,0 +1,53 @@
+import { type Kysely } from 'kysely';
+import { ExecutionJobStatus, 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 { ExpiredJobInfo } from './job-queue.js';
+/**
+ * Whether ANYTHING could ever run a job with these selectors — a registered
+ * agent (regardless of capacity) or a scaler backend able to spawn one.
+ *
+ * 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 and on
+ * how quickly the job settles, never safety — a job that reads routable simply
+ * falls through to the queue-timeout backstop.
+ */
+export type CanRouteLabels = (requiredLabels: string[], requiredPatterns: LabelMatcher[], excludeLabels: string[], excludePatterns: LabelMatcher[]) => boolean;
+/** The routing facts a verdict is computed from. */
+export type JobRoutingFacts = Pick<ExpiredJobInfo, 'lastProvisioningError' | 'runsOnLabels' | 'runsOnPatterns' | 'excludeLabels' | 'excludePatterns'>;
+/** Everything {@link terminalizeUnroutableJob} needs to settle a job. */
+export interface TerminalizeDeps {
+    db: Kysely<Database>;
+    executionTracker: ExecutionTracker;
+    checkRunReporter?: Pick<CheckRunReporter, 'updateJobStatus'>;
+    canRouteLabels?: CanRouteLabels;
+}
+export declare function unroutableMessage(job: JobRoutingFacts): string;
+/**
+ * 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).
+ *
+ * Shared by the unroutable probe (which asks on a short tick, gated by a grace
+ * window) and the queue-expiry sweep (which asks once at expiry, as the
+ * backstop). One verdict, two moments in time — a second copy of this logic is
+ * exactly the drift this module exists to prevent.
+ */
+export declare function classifyUnroutable(job: JobRoutingFacts, canRouteLabels?: CanRouteLabels): {
+    status: ExecutionJobStatus;
+    errorMessage: string;
+    unroutable: boolean;
+};
+/**
+ * Settle one never-dispatched job: write the terminal status locally, surface
+ * the reason at run level, forward to Platform, and resolve its check run.
+ *
+ * @returns the run id when this call actually terminalized the job (so the
+ * caller can complete the run), or null when another coordinator got there
+ * first or the job was no longer pending.
+ */
+export declare function terminalizeUnroutableJob(deps: TerminalizeDeps, job: ExpiredJobInfo): Promise<string | null>;
+//# sourceMappingURL=terminalize-unroutable.d.ts.map

package/dist/queue/unroutable-probe.d.ts

@@ -0,0 +1,52 @@
+import { type Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { JobQueue, UnroutableCandidate } from './job-queue.js';
+import { type CanRouteLabels } from './terminalize-unroutable.js';
+/**
+ * The shipped default grace, mirrored from `config.ts`. Used only to derive a
+ * sane tick cadence when the env default is 0 (fast-fail disabled at startup
+ * but re-enableable live via the `unroutable_grace_ms` cluster setting).
+ */
+export declare const DEFAULT_UNROUTABLE_GRACE_MS = 120000;
+/**
+ * Probe cadence, derived from the grace rather than configured separately.
+ *
+ * The tick is an implementation detail of the grace window — it only has to be
+ * fine-grained enough that the grace elapses on time — not independent policy,
+ * so it deliberately does not earn its own cluster knob.
+ */
+export declare function probeTickIntervalMs(graceMs: number): number;
+/** Writes the operator-facing routing reason onto a still-queued job. */
+export type SetRoutingReason = (runId: string, jobName: string, reason: string | null) => Promise<void>;
+export interface UnroutableProbeDeps {
+    queue: Pick<JobQueue, 'listUnroutableCandidates' | 'markUnroutableSince' | 'clearUnroutableState' | 'claimUnroutable'>;
+    /** Live read, so an operator changing the knob takes effect without a restart. */
+    getGraceMs: () => Promise<number>;
+    canRouteLabels: CanRouteLabels;
+    setRoutingReason: SetRoutingReason;
+    terminalize: (job: UnroutableCandidate) => Promise<void>;
+    onFastFailed?: () => void;
+    /** Max rows examined per tick. */
+    batchLimit?: number;
+}
+/**
+ * Write the routing reason onto a job that is still waiting to be routed.
+ *
+ * The status guard matters: the reason is a statement about a job that has not
+ * been picked up, so it must never annotate one that already started or
+ * finished between the probe's read and this write.
+ */
+export declare function makeRoutingReasonWriter(db: Kysely<Database>): SetRoutingReason;
+/**
+ * Build the per-tick handler for the unroutable probe.
+ *
+ * The probe consults the SAME routability predicate the queue-expiry sweep uses
+ * — one verdict, two moments in time — but asks on a short tick instead of once
+ * an hour. On the first unroutable verdict it records the reason (so the cause
+ * is visible while the job still waits) and starts a grace clock; only once the
+ * job has been CONTINUOUSLY unroutable for the whole grace does it terminalize.
+ * A job that reads routable again has both cleared, so a scaler reload or an
+ * agent reconnect can never cost it its place in the queue.
+ */
+export declare function createUnroutableProbeHandler(deps: UnroutableProbeDeps): () => Promise<void>;
+//# sourceMappingURL=unroutable-probe.d.ts.map

package/dist/reporting/run-aggregator.d.ts

@@ -13,7 +13,7 @@
  * is warm-only in v1.)
  */
 import type { Kysely } from 'kysely';
-import type { ExecutionJobStatus, InitFailure } from '@kici-dev/engine';
+import { ExecutionJobStatus, type InitFailure } from '@kici-dev/engine';
 import type { Database } from '../db/types.js';
 /** A run-detail step row as queried from execution_steps (warm + cold paths). */
 export interface RunDetailStepRow {
@@ -63,6 +63,7 @@ export interface RunDetailJobRow {
     duration_ms: number | null;
     agent_id: string | null;
     error_message: string | null;
+    routing_reason: string | null;
     runs_on_labels: unknown;
     contexts: unknown;
     skipped_contexts: unknown;
@@ -79,6 +80,21 @@ export interface RunDetailJobLookups {
         runOn: ExecutionJobStatus[];
     }>>;
 }
+/**
+ * The routing reason as a reader should see it.
+ *
+ * `routing_reason` is only meaningful while the job is still waiting to be
+ * routed, and more than twenty call sites move a job out of `pending`/`queued`
+ * — dispatch, cancel, the run-level failure cascades, the stale detector.
+ * Requiring every one of them to also null the column would be fragile in the
+ * one direction that matters: the site somebody forgets renders a finished job
+ * as "waiting for an agent".
+ *
+ * So the guard lives here, at the read boundary both projections share, where
+ * it cannot be forgotten by a writer that does not know this column exists.
+ * The stale bytes may linger in the row; they are never shown.
+ */
+export declare function visibleRoutingReason(status: string, routingReason: string | null): string | null;
 /** Map queried job + step rows into the dashboard run-detail job DTO shape. */
 export declare function buildRunDetailJobs(jobs: RunDetailJobRow[], lookups: RunDetailJobLookups): {
     jobId: string;
@@ -94,6 +110,7 @@ export declare function buildRunDetailJobs(jobs: RunDetailJobRow[], lookups: Run
     agentId: string | null;
     orchestratorId: null;
     errorMessage: string | null;
+    routingReason: string | null;
     runsOnLabels: string[] | null;
     contexts: string[] | null;
     skippedContexts: string[] | null;

package/dist/secrets/pg-secret-store.d.ts

@@ -60,12 +60,30 @@ export declare class PgSecretStore implements SecretStore {
      * Get all secrets for a scope as decrypted key-value pairs.
      */
     getSecrets(orgId: string, scope: string): Promise<Record<string, string>>;
+    /** Check if a scope is internal/operational (always allowed regardless of toggle). */
+    private isInternalScope;
     /**
      * Set (create or update) a secret in a scope.
      * Encrypts the value with AAD = "orgId:scope:key".
+     *
+     * Rejects a key outside `[A-Za-z0-9._-]` before doing anything else. The AAD
+     * is a plain concatenation, so a `:` in the key would let two distinct
+     * locations render one AAD (scope 'b' + key 'c:d' equals scope 'b:c' + key
+     * 'd') and a ciphertext written at one would authenticate at the other. The
+     * check sits ahead of the customerSecretsEnabled gate so internal scopes get
+     * no exemption — the binding has to hold for every writer.
+     *
+     * Callers pass a bare scope path, so the AAD's middle field is colon-free
+     * too: the admin route and the dashboard handler both run the scope
+     * validator immediately before calling in, and `source-store` builds its
+     * scope from a uuid. That precondition is what makes the whole triple
+     * recoverable, and it is the caller's to keep — this method does not
+     * re-check it.
+     *
+     * Write-path only: getSecrets, listKeys, deleteSecret, deleteScope,
+     * renameScope, getAllSecrets and createScope stay unvalidated, which is what
+     * keeps a key stored before this rule readable and deletable.
      */
-    /** Check if a scope is internal/operational (always allowed regardless of toggle). */
-    private isInternalScope;
     setSecret(orgId: string, scope: string, key: string, value: string): Promise<void>;
     /**
      * Delete a secret from a scope.