@kici-dev/orchestrator 0.1.26 → 0.2.0

package/dist/reporting/job-check-run-completion.d.ts

@@ -0,0 +1,50 @@
+import { type CheckRunReporter } from './check-run-reporter.js';
+import type { ExecutionContext } from './execution-tracker.js';
+/**
+ * Job-terminal signal this module reacts to. Shaped after the payload the
+ * execution tracker hands its `onJobComplete` hook — its primary caller — plus
+ * the agent-supplied `data` blob used to build the enriched check-run summary.
+ */
+export interface JobCheckRunCompletionInput {
+    runId: string;
+    jobId: string;
+    jobName: string;
+    /** Raw job status string as recorded by the tracker. */
+    status: string;
+    /** Agent-supplied job payload (step results, error, duration). */
+    data?: Record<string, unknown>;
+    /**
+     * Explicit check-run description, overriding the conclusion mapper's default
+     * wording. A caller that already holds the specific reason a job ended the way
+     * it did passes it here — the queue-expiry sweep's `unroutable` message, for
+     * instance, is the only statement of WHICH `runsOn` selectors went unmatched,
+     * and the mapper's generic phrasing cannot name them.
+     */
+    description?: string;
+}
+/** Collaborators needed to post a job's terminal check-run conclusion. */
+export interface JobCheckRunCompletionDeps {
+    checkRunReporter: Pick<CheckRunReporter, 'updateJobStatus'>;
+    /** Resolves the run's provider/repo/sha context — `ExecutionTracker.getExecutionContext`. */
+    getExecutionContext: (runId: string) => ExecutionContext | undefined;
+}
+/**
+ * Post the terminal conclusion for a job's check run.
+ *
+ * Every job that reaches a terminal state must resolve the check run that
+ * `setPending()` created for it at trigger match. A check run left `queued` is
+ * not cosmetic: branch protection that requires it can never be satisfied, and
+ * a developer reads it as "still running" indefinitely with nothing to point at.
+ *
+ * A non-terminal status is a no-op — a check run is completed once, when the job
+ * stops.
+ *
+ * Never throws. Its callers are hot paths whose remaining work matters more than
+ * this report: the tracker's terminal-job hook runs inside `onJobStatus`, ahead
+ * of the job-complete event emission and the needs/wave scheduler hooks, and the
+ * expiry sweep runs it per job inside a loop. `buildJobFailureDescription` reads
+ * an agent-supplied payload, so a malformed `stepResults` entry is enough to
+ * raise — and a check-run report is not worth stalling a run's scheduling for.
+ */
+export declare function reportJobCheckRunCompletion(deps: JobCheckRunCompletionDeps, input: JobCheckRunCompletionInput): void;
+//# sourceMappingURL=job-check-run-completion.d.ts.map

package/dist/reporting/log-chunk-sink.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The single place that decides what happens to a step-log chunk.
+ *
+ * Both ingresses feed this sink: the local agent WebSocket handler and the
+ * coordinator's peer handler, which receives chunks relayed by a worker
+ * orchestrator. Keeping the policy in one place is what makes the two paths
+ * behave identically — a worker-dispatched job's logs are persisted, counted
+ * and forwarded exactly like a locally-dispatched one's.
+ *
+ * The storage key is derived from `executionTracker.getJobName`, the same call
+ * `ExecutionTracker.onStepStatus` uses to fill `execution_steps.log_path`, so
+ * the reader and the writer cannot disagree about the naming rule.
+ */
+import type { LogStream } from '@kici-dev/engine';
+import type { LogWriter } from './log-writer.js';
+import type { StepLogBuffer } from './step-log-buffer.js';
+/** A chunk whose lines all share one timestamp and one originating stream. */
+export interface NormalizedLogChunk {
+    runId: string;
+    jobId: string;
+    stepIndex: number;
+    lines: string[];
+    timestamp: number;
+    stream?: LogStream;
+}
+/** Which ingress produced the chunk. Stamped onto the two log counters. */
+export type LogChunkSource = 'local' | 'peer';
+export interface LogChunkSinkDeps {
+    /** Ingress this sink instance serves; becomes the `source` metric attribute. */
+    source: LogChunkSource;
+    /** Short in-memory tail feeding the GitHub check-run summary. */
+    stepLogBuffer?: StepLogBuffer;
+    /** Durable step-log persistence. Absent when the orchestrator has no database. */
+    logWriter?: LogWriter;
+    /** Resolves the job name that names the storage path. */
+    executionTracker?: {
+        getJobName(runId: string, jobId: string): string | undefined;
+    };
+    /**
+     * Forward to the Platform for browser fan-out. Absent in independent mode.
+     * The caller wraps the chunk in the `log.chunk` envelope, which keeps this
+     * module free of Platform-protocol knowledge.
+     */
+    forwardToPlatform?: (chunk: NormalizedLogChunk) => void;
+}
+export declare function createLogChunkSink(deps: LogChunkSinkDeps): (chunk: NormalizedLogChunk) => void;
+//# sourceMappingURL=log-chunk-sink.d.ts.map

package/dist/reporting/log-retention.d.ts

@@ -0,0 +1,16 @@
+import type { LogStorage } from './log-storage.js';
+/**
+ * Delete step-log objects older than `ttlDays` in one bulk pass.
+ *
+ * Step-log objects are write-once (appended during the run, untouched after
+ * finalize), so last-modified time is the correct expiry basis — a recent or
+ * still-running run's objects were all written within the window and survive.
+ * `ttlDays <= 0` disables the sweep (returns 0). Expired objects are collected
+ * then bulk-deleted via `deleteMany` (S3 DeleteObjects), so a large sweep is a
+ * handful of API calls, not one-per-object. A delete failure is logged and the
+ * cleanup tick is not aborted.
+ *
+ * @returns Number of objects deleted.
+ */
+export declare function pruneExpiredLogs(storage: LogStorage, ttlDays: number, now?: Date): Promise<number>;
+//# sourceMappingURL=log-retention.d.ts.map

package/dist/reporting/log-storage.d.ts

@@ -2,14 +2,33 @@
  * Log storage abstraction for the orchestrator.
  *
  * Provides a pluggable backend interface for persisting execution logs.
- * Unlike CacheStorage, log storage has NO TTL semantics -- logs persist
- * indefinitely and the customer manages their own storage lifecycle.
+ * Retention on the S3 backend is bounded by the orchestrator cleanup sweep
+ * (`KICI_STEP_LOG_TTL_DAYS`, default 90; 0 disables it); the filesystem backend
+ * leaves lifecycle to the operator.
  *
  * Backends: FilesystemLogStorage, S3LogStorage
  *
  * Log file layout: executions/{runId}/job-{name}/step-{index}.log
  * Format: JSONL (one JSON object per line with timestamp, level, message, metadata)
  */
+/**
+ * Assert that a logical log path is safe to hand to a storage backend.
+ *
+ * The invariant every backend relies on: a log path is relative, contains no
+ * `..` segment, and carries no NUL byte. Both backends call this at their own
+ * boundary, so a malformed key is refused identically whichever backend the
+ * operator configured, and a new caller is guarded on arrival rather than by
+ * remembering to validate.
+ *
+ * The `..` test is per-segment, not a substring match: a job name such as
+ * `job-a..b` is legitimate and is accepted.
+ *
+ * `FilesystemLogStorage.fullPath()` re-states the same invariant physically,
+ * comparing the resolved absolute path against the resolved root. Both checks
+ * are lexical: neither resolves symlinks, so a symlink planted inside the log
+ * root still redirects a logically-clean path through it.
+ */
+export declare function assertSafeLogPath(path: string): void;
 /**
  * Read result from LogStorage.read().
  * Supports cursor-based pagination for large log files.
@@ -34,17 +53,54 @@ export interface LogReadOptions {
 /**
  * Pluggable log storage interface.
  *
- * All operations are async. No TTL -- logs persist indefinitely.
+ * All operations are async. Retention is enforced by the cleanup sweep on the
+ * S3 backend (see `pruneExpiredLogs`); the filesystem backend is operator-managed.
  */
 export interface LogStorage {
-    /** Append lines to a log file. Creates the file (and directories) if it doesn't exist. */
+    /**
+     * Append lines to a log file, immediately durable. Creates the file (and
+     * directories) if it doesn't exist. Used by single-shot writers (webhook
+     * payloads, rerun payloads, orchestration logs) that write once and expect
+     * the content to be readable without any subsequent finalize call.
+     */
     append(path: string, data: string): Promise<void>;
+    /**
+     * High-frequency append-only log write. Durability is guaranteed by a
+     * subsequent finalize(path) (called at run completion). S3 buffers per key
+     * and seals immutable segments on a size/time threshold; the filesystem
+     * appends immediately (appendFile is already durable).
+     */
+    appendStreaming(path: string, data: string): Promise<void>;
+    /**
+     * Seal any buffered-but-unwritten content for a path. S3 flushes its current
+     * tail segment; the filesystem is a no-op. Safe on any path — a no-op when
+     * nothing is buffered.
+     */
+    finalize(path: string): Promise<void>;
     /** Read log file content. Returns { data, cursor, complete } for pagination. */
     read(path: string, options?: LogReadOptions): Promise<LogReadResult>;
     /** Check if a log file exists. */
     exists(path: string): Promise<boolean>;
     /** List files matching a prefix (directory listing). */
     list(prefix: string): Promise<string[]>;
+    /**
+     * List every physical object under a prefix with its last-modified time,
+     * `path` relative to the storage prefix. Unlike {@link LogStorage.list} this
+     * does NOT collapse S3 segment objects (`.../seg-NNNNNN`) to their logical
+     * step path — the retention sweep must see and delete each physical object,
+     * and each segment carries its own last-modified time. Step-log objects are
+     * write-once, so last-modified is the correct expiry basis.
+     */
+    listWithMetadata(prefix: string): Promise<Array<{
+        path: string;
+        lastModified: Date;
+    }>>;
+    /**
+     * Bulk-delete objects by their storage-relative path (as returned by
+     * {@link LogStorage.listWithMetadata}). S3 uses `DeleteObjects` (≤1000
+     * keys/call, chunked); missing keys are no-ops. Returns the count deleted.
+     */
+    deleteMany(paths: string[]): Promise<number>;
 }
 /**
  * Configuration for creating a log storage backend.
@@ -61,6 +117,10 @@ type LogStorageConfig = {
     endpoint?: string;
     /** Use path-style access instead of virtual-hosted-style (required for most S3-compatible services) */
     forcePathStyle?: boolean;
+    /** Seal a step-log segment once the in-memory buffer reaches this many bytes. */
+    segmentFlushBytes: number;
+    /** Seal a step-log segment once the oldest buffered byte reaches this age (ms). */
+    segmentFlushMs: number;
 };
 /**
  * Factory function to create the appropriate LogStorage backend.

package/dist/reporting/log-writer.d.ts

@@ -5,10 +5,14 @@
  * and metadata fields. Lines are written to the standard log path layout:
  * executions/{runId}/job-{name}/step-{index}.log
  *
- * For filesystem storage, data is appended immediately (no buffering).
- * For S3 storage, the LogStorage backend handles read-concat-put.
+ * Step-log writes go through the high-frequency `appendStreaming` verb: the
+ * filesystem backend appends immediately (no buffering); the S3 backend buffers
+ * per step key and seals immutable append-only segments. `drain(runId)` awaits
+ * the in-flight appends and then finalizes each step path so the S3 tail
+ * segment is sealed before a reader declares the stream complete.
  */
 import type { LogStorage } from './log-storage.js';
+import { LogStream } from '@kici-dev/engine';
 import type { ObserverRegistry } from '../ws/observer-registry.js';
 interface LogWriterDeps {
     logStorage: LogStorage;
@@ -32,13 +36,22 @@ export declare class LogWriter {
      * disk, dropping it from a blocking `kici run remote` follow.
      */
     private readonly pendingAppends;
+    /**
+     * Log paths written for each run, populated in `appendChunk`. `drain(runId)`
+     * finalizes each one so the S3 backend seals its buffered tail segment before
+     * a reader declares the stream complete. The filesystem backend's `finalize`
+     * is a no-op.
+     */
+    private readonly runPaths;
     constructor(deps: LogWriterDeps);
     /**
      * Await every in-flight log append for `runId` that was registered before
-     * this call. Settles even if an append rejected (errors are already logged
-     * by `appendChunk`); the point is ordering, not error propagation. New
-     * appends started after this call are not waited on — a terminal run emits
-     * no further chunks, so the snapshot taken at call time is complete.
+     * this call, then seal each step log's buffered tail segment so the durable
+     * S3 record is complete. Settles even if an append rejected (errors are
+     * already logged by `appendChunk`); the point is ordering, not error
+     * propagation. New appends started after this call are not waited on — a
+     * terminal run emits no further chunks, so the snapshot taken at call time is
+     * complete.
      */
     drain(runId: string): Promise<void>;
     /**
@@ -57,8 +70,10 @@ export declare class LogWriter {
      * @param timestamp - Timestamp from the agent message (epoch ms)
      * @param jobId - Job ID for observer broadcasting (optional)
      * @param stepName - Step name for observer broadcasting (optional)
+     * @param stream - Which subprocess stream the lines came from. Absent means
+     *   the agent did not report one, which is recorded as `stdout`.
      */
-    appendChunk(runId: string, jobName: string, stepIndex: number, lines: string[], timestamp: number, jobId?: string, stepName?: string): Promise<void>;
+    appendChunk(runId: string, jobName: string, stepIndex: number, lines: string[], timestamp: number, jobId?: string, stepName?: string, stream?: LogStream): Promise<void>;
 }
 export {};
 //# sourceMappingURL=log-writer.d.ts.map

package/dist/reporting/peer-log-normalize.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Convert a worker-relayed `peer.log.chunk` into the chunk shape the log sink
+ * consumes.
+ *
+ * The peer frame carries a timestamp and an originating stream per line, while
+ * the sink (and `LogWriter.appendChunk` beneath it) takes one of each per
+ * chunk. Grouping consecutive lines that agree on both is lossless and keeps
+ * line order intact. A worker today gives every line in a chunk the same
+ * timestamp and stream, so this yields a single group in practice.
+ */
+import type { PeerLogChunk } from '@kici-dev/engine';
+import type { NormalizedLogChunk } from './log-chunk-sink.js';
+export declare function normalizePeerLogChunk(chunk: PeerLogChunk): NormalizedLogChunk[];
+//# sourceMappingURL=peer-log-normalize.d.ts.map

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

@@ -34,12 +34,6 @@ export interface RunDetailStepRow {
 }
 /** Map a step row to the dashboard run-detail step shape (epoch-ms timestamps). */
 export declare function mapRunDetailStep(step: RunDetailStepRow): {
-    groupId?: string | undefined;
-    concurrencyKind?: string | undefined;
-    driftSummary?: string | undefined;
-    checkOutcome?: string | undefined;
-    secretsAccessed: string | null;
-    stepType?: string | undefined;
     stepIndex: number;
     stepName: string;
     status: string;
@@ -48,6 +42,12 @@ export declare function mapRunDetailStep(step: RunDetailStepRow): {
     durationMs: number | null;
     exitCode: number | null;
     errorMessage: string | null;
+    stepType?: string | undefined;
+    secretsAccessed: string | null;
+    checkOutcome?: string | undefined;
+    driftSummary?: string | undefined;
+    concurrencyKind?: string | undefined;
+    groupId?: string | undefined;
 };
 /** A run-detail job row as queried from execution_jobs (warm + cold paths). */
 export interface RunDetailJobRow {
@@ -64,8 +64,8 @@ export interface RunDetailJobRow {
     agent_id: string | null;
     error_message: string | null;
     runs_on_labels: unknown;
-    environments: unknown;
-    skipped_environments: unknown;
+    contexts: unknown;
+    skipped_contexts: unknown;
     env_warning: string | null;
     outputs: unknown;
     init_failure: unknown;
@@ -81,32 +81,6 @@ export interface RunDetailJobLookups {
 }
 /** Map queried job + step rows into the dashboard run-detail job DTO shape. */
 export declare function buildRunDetailJobs(jobs: RunDetailJobRow[], lookups: RunDetailJobLookups): {
-    needs: {
-        upstreamName: string;
-        runOn: ExecutionJobStatus[];
-    }[] | null;
-    steps: {
-        groupId?: string | undefined;
-        concurrencyKind?: string | undefined;
-        driftSummary?: string | undefined;
-        checkOutcome?: string | undefined;
-        secretsAccessed: string | null;
-        stepType?: string | undefined;
-        stepIndex: number;
-        stepName: string;
-        status: string;
-        startedAt: number | null;
-        completedAt: number | null;
-        durationMs: number | null;
-        exitCode: number | null;
-        errorMessage: string | null;
-    }[];
-    initFailure?: {
-        scope: "job" | "run";
-        category: "secret_resolution" | "install_secrets" | "lock_resolution" | "build_coordination" | "environment_rules" | "dynamic_eval" | "no_agent" | "matrix_expansion";
-        message: string;
-        jobName?: string | undefined;
-    } | undefined;
     jobId: string;
     jobName: string;
     status: string;
@@ -121,11 +95,37 @@ export declare function buildRunDetailJobs(jobs: RunDetailJobRow[], lookups: Run
     orchestratorId: null;
     errorMessage: string | null;
     runsOnLabels: string[] | null;
-    environments: string[] | null;
-    skippedEnvironments: string[] | null;
+    contexts: string[] | null;
+    skippedContexts: string[] | null;
     envWarning: string | null;
     outputs: any;
     secretOutputKeys: string[] | null;
+    initFailure?: {
+        scope: "job" | "run";
+        category: "approval_misconfig" | "build_coordination" | "context_rules" | "dynamic_eval" | "install_secrets" | "lock_resolution" | "matrix_expansion" | "no_agent" | "sandbox_denied" | "secret_resolution" | "trust_policy";
+        message: string;
+        jobName?: string | undefined;
+    } | undefined;
+    needs: {
+        upstreamName: string;
+        runOn: ExecutionJobStatus[];
+    }[] | null;
+    steps: {
+        stepIndex: number;
+        stepName: string;
+        status: string;
+        startedAt: number | null;
+        completedAt: number | null;
+        durationMs: number | null;
+        exitCode: number | null;
+        errorMessage: string | null;
+        stepType?: string | undefined;
+        secretsAccessed: string | null;
+        checkOutcome?: string | undefined;
+        driftSummary?: string | undefined;
+        concurrencyKind?: string | undefined;
+        groupId?: string | undefined;
+    }[];
 }[];
 /** A dashboard-shaped run-detail job (epoch-ms timestamps). */
 export type CanonicalRunDetailJob = ReturnType<typeof buildRunDetailJobs>[number];

package/dist/reporting/s3-log-storage.d.ts

@@ -1,14 +1,37 @@
 /**
  * S3-backed log storage.
  *
- * Stores execution logs in S3. No TTL -- logs persist indefinitely.
+ * Stores execution logs in S3. Retention is bounded by the orchestrator cleanup
+ * sweep, which bulk-deletes objects older than `KICI_STEP_LOG_TTL_DAYS` (default
+ * 90; 0 disables the sweep for operators running their own bucket lifecycle).
  *
- * Implementation notes:
- * - append() reads existing content + concatenates + puts back (acceptable
- *   for the sequential step model where max ~10MB per step)
- * - read() uses Range header for cursor-based pagination
- * - exists() uses HeadObject
- * - list() uses ListObjectsV2 with prefix
+ * Two write verbs with different durability contracts:
+ *
+ * - append() is an immediately-durable read-modify-write: GetObject the whole
+ *   object, concatenate, PutObject it back. Correct for single-shot writers
+ *   (webhook delivery payloads, rerun payloads, orchestration logs) that write
+ *   once and read back without any finalize — N=1 means no amplification and no
+ *   race. Its content is a plain single object at objectKey(path).
+ * - appendStreaming() is the high-frequency step-log verb. S3 has no native
+ *   append primitive, so it buffers chunks per step key in memory and seals an
+ *   immutable `{objectKey(path)}/seg-NNNNNN` object (one PutObject, unique key)
+ *   once the buffer reaches segmentFlushBytes OR its oldest byte reaches
+ *   segmentFlushMs. Each byte is written exactly once (no O(N^2) amplification)
+ *   and the unique seal key means concurrent appends to the same step can never
+ *   overwrite one another. Durability of the final tail is guaranteed by
+ *   finalize(path) at run completion.
+ *
+ * - finalize() seals the remaining tail buffer for a step key.
+ * - read() lists sealed segments (plus any legacy/single object written by
+ *   append()) and streams them via the byte-offset cursor.
+ * - exists()/list() are segment-aware: `exists` is true when a single object or
+ *   any segment is present; `list` collapses segment keys to their logical step
+ *   path.
+ *
+ * All appendStreaming/finalize operations for one step key run through a
+ * sequential execution chain so the in-memory buffer and seq counter are the
+ * authoritative single writer even when the caller fires appends without
+ * awaiting.
  *
  * Uses AWS SDK v3 modular imports -- only loaded when S3 storage is configured.
  */
@@ -21,22 +44,93 @@ interface S3LogStorageOptions {
     endpoint?: string;
     /** Use path-style access instead of virtual-hosted-style (required for most S3-compatible services) */
     forcePathStyle?: boolean;
+    /** Seal a step-log segment once the in-memory buffer reaches this many bytes. */
+    segmentFlushBytes: number;
+    /** Seal a step-log segment once the oldest buffered byte reaches this age (ms). */
+    segmentFlushMs: number;
 }
 export declare class S3LogStorage implements LogStorage {
     private readonly client;
     private readonly bucket;
     private readonly prefix;
+    private readonly segmentFlushBytes;
+    private readonly segmentFlushMs;
+    /** Per-key in-memory tail buffers awaiting seal (appendStreaming path). */
+    private readonly buffers;
+    /** Per-key sequential execution chain (serializes appendStreaming/finalize). */
+    private readonly locks;
     constructor(options: S3LogStorageOptions);
-    /** Build the full S3 object key from a log path. */
+    /**
+     * Build the full S3 object key from a log path.
+     *
+     * The assert is not traversal protection — S3 keys are opaque byte strings,
+     * so `..` is a literal segment and this concatenation cannot escape the
+     * prefix. It refuses to mint a malformed key at all: `list()` and
+     * `listWithMetadata()` rebuild storage-relative paths by slicing the prefix
+     * off, so a key carrying `..` or a leading `/` would be handed back to the
+     * caller as an odd relative path — and on a filesystem-backed peer that path
+     * reaches a resolve. Keep it; it is deliberate.
+     *
+     * Removals do NOT go through here: see {@link S3LogStorage.deleteKey}.
+     */
     private objectKey;
+    /**
+     * Object key for a removal, built without the minting assert.
+     *
+     * `deleteMany` consumes this store's own `listWithMetadata()` output, which
+     * reports whatever keys the bucket actually holds — including a legacy
+     * malformed one written before `objectKey()` began refusing them. Routing a
+     * removal through the minting assert would throw while building the batch,
+     * so one such object would abort the whole retention sweep and leave every
+     * expired object in place forever. There is no protection to lose: an S3 key
+     * is an opaque byte string, so a `..` segment is literal and this
+     * concatenation addresses an object inside the prefix or nothing at all.
+     */
+    private deleteKey;
+    /** Segment object key for a given sequence number (zero-padded to 6 digits). */
+    private segKey;
     /** Check if an error is a "not found" error (NoSuchKey, NotFound, 404). */
     private isNotFoundError;
     /** Read the full content of an S3 object as a string. Returns null if not found. */
     private getContent;
+    /**
+     * Run `fn` after every previously-queued operation for `key` has settled, so
+     * all appendStreaming/finalize calls for one step key execute strictly in
+     * order. The chain swallows prior errors (they are surfaced to their own
+     * caller) so one failed op does not wedge the key.
+     */
+    private runExclusive;
     append(path: string, data: string): Promise<void>;
+    /**
+     * Highest existing segment number under a key (for mid-run redeploy
+     * continuity), + 1. Returns 0 when no segments exist yet.
+     */
+    private nextSeq;
+    /** Seal the buffer as the next immutable segment object. */
+    private seal;
+    appendStreaming(path: string, data: string): Promise<void>;
+    finalize(path: string): Promise<void>;
+    /**
+     * Single-object size (or null) + sealed segments in ascending seq order for a
+     * key. The single object is the content written by append() (single-shot
+     * writers) or any legacy step log written before the append-only change.
+     */
+    private layout;
+    /** Fetch an inclusive byte range from one object. */
+    private getRange;
+    /**
+     * Map a global byte cursor + limit onto per-object range reads across an
+     * ordered entry list. Returns the reads to perform and the total byte size.
+     */
+    private planReads;
     read(path: string, options?: LogReadOptions): Promise<LogReadResult>;
     exists(path: string): Promise<boolean>;
     list(prefix: string): Promise<string[]>;
+    listWithMetadata(prefix: string): Promise<Array<{
+        path: string;
+        lastModified: Date;
+    }>>;
+    deleteMany(paths: string[]): Promise<number>;
 }
 export {};
 //# sourceMappingURL=s3-log-storage.d.ts.map

package/dist/routes/admin-auth.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Shared Bearer-token auth middleware for the orchestrator's admin routes.
+ *
+ * One factory serves every DB-backed admin router, which is what makes the
+ * error boundary universal: a router that forgets to wrap `validate()` cannot
+ * exist, because no router writes that call itself.
+ *
+ * Three outcomes, deliberately distinct:
+ *   - header absent / not `Bearer <token>`   -> 401 AUTH_ERROR.missing
+ *   - token unknown / revoked / expired      -> 401 AUTH_ERROR.invalid
+ *   - validation could not be completed      -> 503 AUTH_ERROR.unavailable
+ *
+ * The third is the reason this file exists. `validate()` returns `null` for a
+ * bad credential, so it only throws when the lookup itself fails (unreachable
+ * DB, exhausted pool, failover). That is not the caller's fault and is not a
+ * bug in this request: the server cannot authenticate anyone right now, which
+ * is what 503 means. It also keeps a DB blip out of the 5xx error-rate signal
+ * that alerting reads as an application outage.
+ *
+ * The boundary fails closed: an unresolvable auth decision is a rejection with
+ * a 5xx, never a fall-through to the protected handler.
+ */
+import type { Context, MiddlewareHandler } from 'hono';
+import type { Role } from '../secrets/rbac.js';
+/**
+ * The three admin-auth response bodies.
+ *
+ * A single map rather than string literals repeated across every admin router:
+ * the 401 wordings are observed by operators and by E2E assertions, so they are
+ * pinned in exactly one place.
+ */
+export declare const AUTH_ERROR: {
+    readonly missing: 'Missing authorization';
+    readonly invalid: 'Invalid or expired token';
+    readonly unavailable: 'Authentication unavailable';
+};
+/** What a successful admin-token validation yields. */
+export interface AuthTokenInfo {
+    id: string;
+    role: Role;
+    routingKey: string | null;
+    label: string;
+}
+/** The slice of TokenManager this middleware needs (keeps tests trivial to fake). */
+export interface AuthTokenValidator {
+    validate(token: string): Promise<AuthTokenInfo | null>;
+}
+/**
+ * The result of resolving one `Authorization` header.
+ *
+ * Failures carry the status and body rather than a `Response` so a caller that
+ * is not a middleware (the inline run-cancel route on the coordinator app) can
+ * answer with the identical shape.
+ */
+export type BearerAuthOutcome = {
+    ok: true;
+    tokenInfo: AuthTokenInfo;
+} | {
+    ok: false;
+    status: 401 | 503;
+    error: string;
+};
+export interface BearerAuthDeps {
+    tokenManager: AuthTokenValidator;
+    /** Route-family label recorded on the 503 log line (e.g. 'admin-runs'). */
+    scope: string;
+    /** Overridable for tests; defaults to the module logger. */
+    logger?: {
+        error(msg: string, meta?: Record<string, unknown>): void;
+    };
+}
+/**
+ * Resolve one request's `Authorization` header into an authenticated token or
+ * a rejection. This is the boundary itself; the middleware below is a thin
+ * wrapper so a route that needs the token info inline can share it.
+ *
+ * @param c - The request context (only the header, method, and path are read).
+ * @param deps - Token validator, a scope label for logs, and an optional logger.
+ * @returns The token info, or the status + body to answer with.
+ */
+export declare function resolveBearerAuth(c: Context<any>, deps: BearerAuthDeps): Promise<BearerAuthOutcome>;
+/**
+ * Build the bearer-auth middleware for one admin route family.
+ *
+ * @param deps - Token validator, a scope label for logs, and an optional logger.
+ * @returns A Hono middleware that authenticates or rejects; it never calls
+ *   `next()` on an unresolved credential.
+ */
+export declare function createBearerAuthMiddleware(deps: BearerAuthDeps): MiddlewareHandler<any>;
+//# sourceMappingURL=admin-auth.d.ts.map

package/dist/routes/admin-cluster-settings.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Admin API routes for cluster-global (fleet-wide) orchestrator tunables.
+ *
+ * Exposes GET / PATCH `/api/v1/admin/cluster-settings` so `kici-admin
+ * cluster-settings` can read and write the single `cluster_settings` row
+ * (id='default') without going through the Platform dashboard proxy — the CLI
+ * stays operable even when Platform is unavailable.
+ *
+ * These knobs are fleet-wide, not per-tenant, so the route is deliberately NOT
+ * under `/orgs/:customerId/*`. Mutations require the `secret.write` RBAC
+ * capability (already granted to admin / owner roles), matching the gating
+ * posture used by `admin-org-settings.ts`.
+ */
+import { Hono } from 'hono';
+import { type Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+interface ClusterSettingsRouteDeps {
+    db: Kysely<Database>;
+    rbac: RbacEnforcer;
+}
+type AdminEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
+export declare function createClusterSettingsRoutes(deps: ClusterSettingsRouteDeps): Hono<AdminEnv>;
+export {};
+//# sourceMappingURL=admin-cluster-settings.d.ts.map