@kici-dev/orchestrator 0.1.3 → 0.1.6

package/dist/agent/dispatcher.d.ts

@@ -206,6 +206,32 @@ export declare class Dispatcher {
      * from a previous orchestrator instance.
      */
     startRecoveryTimer(jobId: string, agentId: string, runId: string): Promise<void>;
+    /**
+     * Rebuild the in-memory `recoveringJobs` Map from persisted
+     * `dispatch_queue` rows after a coord boot / Raft leader switch.
+     *
+     * For each `status='recovering'` row:
+     *   - if `recovery_deadline` is in the future, recreate a setTimeout
+     *     with the remaining window so the local sweep still fires.
+     *   - if the deadline is already in the past, leave the row alone —
+     *     the leader-gated `sweepExpiredRecoveries()` will pick it up on
+     *     its next tick (which avoids two coords racing to mark the same
+     *     job failed during recovery).
+     *   - rows with NULL deadline (pre-migration recovering jobs) are
+     *     fast-failed by the sweep on its first run.
+     */
+    recoverState(): Promise<void>;
+    /**
+     * Leader-gated sweep: mark every `recovering` row whose
+     * `recovery_deadline < now` as `failed` and fire the per-job
+     * `onRecoveryTimeout` hook. Intended to run on the Raft leader at a
+     * fixed interval so jobs whose owning coord crashed mid-recovery
+     * still reach a terminal state.
+     *
+     * Safe to call on non-leaders (idempotent due to the WHERE clause)
+     * but skipping the call on followers avoids redundant DB updates.
+     */
+    sweepExpiredRecoveries(): Promise<number>;
     /**
      * Stop all recovery timers. Called during graceful shutdown.
      */

package/dist/agent/ownership-tracker.d.ts

@@ -13,6 +13,18 @@
 interface OwnershipTrackerOpts {
     /** Check if a job is owned by the given agent (active or in grace window). */
     isJobOwnedByAgent: (agentId: string, jobId: string) => boolean;
+    /**
+     * Optional DB-backed fallback. Returns true when the orchestrator
+     * DB shows the (agent, job) pair as previously owned by this coord
+     * OR a sibling coord — i.e. either currently `dispatched`/`recovering`
+     * with the same `agent_id` / `recovery_agent_id`, or recently
+     * `completed`/`failed`. When a Raft leader switch wipes the
+     * in-memory `agentJobs` Map on the replacement coord, this fallback
+     * accepts late `log.chunk` / `step.status` chunks from agents that
+     * are still draining instead of rejecting them as ownership
+     * violations.
+     */
+    isJobOwnedByAgentInDb?: (agentId: string, jobId: string) => Promise<boolean>;
     /** Callback to disconnect an agent after escalation. */
     onDisconnect: (agentId: string, reason: string) => void;
     /** Number of violations before escalation (default: 5). */
@@ -22,23 +34,53 @@ interface OwnershipTrackerOpts {
 }
 export declare class OwnershipTracker {
     private readonly isJobOwnedByAgent;
+    private readonly isJobOwnedByAgentInDb?;
     private readonly onDisconnect;
     private readonly violationThreshold;
     private readonly violationWindowMs;
     private readonly violations;
+    /**
+     * L1 cache of `(agentId, jobId)` pairs proven by a positive DB
+     * fallback. Pre-empts a synchronous warn-and-reject for the very
+     * next chunk on the same pair, since `checkOwnership` is called
+     * once per inbound message and the local Map repopulation lags
+     * behind. The cache is intentionally small (per-agent capped) and
+     * is cleaned on agent disconnect via `cleanup(agentId)`.
+     */
+    private readonly dbAccepted;
     constructor(opts: OwnershipTrackerOpts);
     /**
-     * Check if an agent owns a job. Returns true if ownership is valid.
-     * On violation: logs warning, records violation, may escalate to disconnect.
+     * Synchronous ownership check. Returns true if ownership is valid
+     * per the in-memory dispatcher OR a previously-accepted DB fallback.
+     *
+     * Returns false WITHOUT recording a violation when a DB fallback is
+     * configured: the caller is expected to invoke `validateAsync` to
+     * confirm or reject the ownership before treating it as a real
+     * violation. This makes the writer idempotent across HA failover —
+     * a `log.chunk` arriving on the replacement coord doesn't get
+     * counted as a violation just because the local Map is empty.
      */
     checkOwnership(agentId: string, jobId: string, messageType: string): boolean;
+    /**
+     * Async fallback used by message handlers that want HA-safe
+     * acceptance of post-failover chunks. Returns true if the DB shows
+     * the (agent, job) pair as currently or recently owned by any coord
+     * in the cluster. On true, caches the result so subsequent same-pair
+     * chunks return true synchronously via `checkOwnership`. On false,
+     * records a violation exactly once (no recursive recordViolation
+     * from the synchronous call site — `checkOwnership` skipped it
+     * when the DB fallback was configured).
+     */
+    validateAsync(agentId: string, jobId: string, messageType: string): Promise<boolean>;
     /**
      * Record a violation for an agent. If threshold is exceeded within the
      * violation window, triggers disconnect escalation.
      */
     private recordViolation;
     /**
-     * Clean up violation tracking for a disconnected agent.
+     * Clean up violation tracking AND the DB-accepted cache for a
+     * disconnected agent. Avoids cross-agent leakage when the same
+     * agent id is later reused.
      */
     cleanup(agentId: string): void;
 }

package/dist/app.d.ts

@@ -34,7 +34,7 @@ import type { PendingBuildTracker } from './cache/index.js';
 import type { PendingInitTracker } from './cache/index.js';
 import type { PendingDynamicTracker } from './cache/index.js';
 import type { CacheStorage } from './storage/types.js';
-import { type CommitStatusReporter } from './reporting/commit-status.js';
+import { type CheckRunReporter } from './reporting/check-run-reporter.js';
 import type { ExecutionTracker } from './reporting/execution-tracker.js';
 import type { LogWriter } from './reporting/log-writer.js';
 import type { LogStorage } from './reporting/log-storage.js';
@@ -108,7 +108,7 @@ export interface AppDependencies {
     /** Pending dynamic tracker for DynamicJobFn evaluation coordination. */
     pendingDynamics?: PendingDynamicTracker;
     /** Commit status reporter for setting pending/success/failure/error on commits. Optional. */
-    commitStatusReporter?: CommitStatusReporter;
+    checkRunReporter?: CheckRunReporter;
     /** Execution tracker for DB persistence of execution state. Optional — requires database. */
     executionTracker?: ExecutionTracker;
     /** Log writer for persisting agent log chunks. Optional — requires database. */
@@ -123,6 +123,12 @@ export interface AppDependencies {
     ownershipTracker?: OwnershipTracker;
     /** Admin API route dependencies. Optional -- only mounted when secrets management is configured. */
     adminDeps?: AdminRouteDeps;
+    /**
+     * Resolves the public webhook URL for a newly added source (for
+     * `kici-admin source add` output). Built by the entry point where the
+     * Platform client + config are in scope; passed into the admin source routes.
+     */
+    resolveSourceWebhookUrl?: AdminRouteDeps['resolveSourceWebhookUrl'];
     /** Config admin API route dependencies. Optional -- mounted when config management is available. */
     configRouteDeps?: ConfigRouteDeps;
     /** Event router for internal event delivery. Optional -- if not set, event routing is inactive. */
@@ -202,7 +208,7 @@ export interface AppDependencies {
 /**
  * In-memory cache for step source locations extracted from lock files.
  * Keyed by `workflowName:jobName`, stores source location arrays indexed by step index.
- * Populated during webhook processing, used by CommitStatusReporter for annotations.
+ * Populated during webhook processing, used by CheckRunReporter for annotations.
  */
 export declare class SourceLocationStore {
     private readonly cache;

package/dist/audit/access-log.d.ts

@@ -15,6 +15,13 @@ export interface AccessLogRecord {
     source: AccessLogSource;
     outcome: AccessLogOutcome;
     errorMessage?: string | null;
+    /**
+     * Extra key/value pairs merged into `actor_meta` on insert. Lets
+     * callers attach action-specific context (e.g. which dashboard-write
+     * operation flipped) without overloading other columns. Values must
+     * be JSON-serialisable.
+     */
+    meta?: Record<string, unknown>;
 }
 export interface AccessLogQueryFilter {
     orgId?: string;

package/dist/cli/api-client.d.ts

@@ -59,6 +59,10 @@ export declare class AdminApiClient {
      * Public PATCH request returning parsed JSON.
      */
     patch<T>(path: string, body: unknown): Promise<T>;
+    /**
+     * Public PUT request returning parsed JSON.
+     */
+    put<T>(path: string, body: unknown): Promise<T>;
     /**
      * Public DELETE request returning parsed JSON.
      */
@@ -75,6 +79,16 @@ export declare class AdminApiClient {
     }>;
     setSecret(orgId: string, scope: string, key: string, value: string): Promise<void>;
     deleteSecret(orgId: string, scope: string, key: string): Promise<void>;
+    listVariables(orgId: string, environment: string): Promise<{
+        variables: Array<{
+            key: string;
+            value: string;
+            locked: boolean;
+            updated_at: string;
+        }>;
+    }>;
+    setVariable(orgId: string, environment: string, key: string, value: string, locked?: boolean): Promise<void>;
+    deleteVariable(orgId: string, environment: string, key: string): Promise<void>;
     rotateKey(): Promise<{
         reEncrypted: number;
         reEncryptedConfigs: number;

package/dist/cli/commands/cluster-name.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Cluster-name management commands for kici-admin.
+ *
+ * Subcommand namespace: `kici-admin cluster-name {get,set}`.
+ *
+ * The cluster name is the human-friendly identifier that surfaces on
+ * Platform's connection registry and in the dashboard's per-orch URL
+ * segment. Mutating it requires admin access (RBAC `secret.write`).
+ *
+ * Talks to the orchestrator admin API directly (not the Platform
+ * dashboard proxy), so the CLI stays operable even when Platform is
+ * unavailable. Backed by
+ * `packages/orchestrator/src/routes/admin-cluster-name.ts`.
+ */
+import type { Command } from 'commander';
+import type { AdminApiClient } from '../api-client.js';
+export declare function registerClusterNameCommands(program: Command, getClient: () => AdminApiClient): void;
+//# sourceMappingURL=cluster-name.d.ts.map

package/dist/cli/commands/db.d.ts

@@ -1,12 +1,15 @@
 /**
  * Database management commands for kici-admin.
  *
- *   db migrate              Run pending migrations (HTTP — orchestrator must be up)
- *   db fresh                DROP + CREATE + migrate + store content hash (direct DB)
- *   db ensure <name>        CREATE DATABASE IF NOT EXISTS (direct DB)
- *   db create-role          CREATE ROLE LOGIN [CREATEDB] (direct DB)
- *   db create-readonly-user Read-only role + GRANT SELECT (direct DB)
- *   db check-schema         Compare bundled migrations vs live schema (direct DB)
+ *   db migrate                    Run pending migrations (HTTP — orchestrator must be up)
+ *   db fresh                      DROP + CREATE + migrate + store content hash (direct DB)
+ *   db ensure <name>              CREATE DATABASE IF NOT EXISTS (direct DB)
+ *   db create-role                CREATE ROLE LOGIN [CREATEDB] (direct DB)
+ *   db create-readonly-user       Read-only role + GRANT SELECT (direct DB)
+ *   db check-schema               Compare bundled migrations vs live schema (direct DB)
+ *   db collation-check            Check pg_database.datcollversion vs running libc (direct DB)
+ *   db reindex                    REINDEX DATABASE CONCURRENTLY (direct DB)
+ *   db refresh-collation-version  ALTER DATABASE REFRESH COLLATION VERSION (direct DB)
  *
  * The direct-DB subcommands cannot go through HTTP because the target database
  * may not exist yet or is about to be dropped. They follow the same pattern

package/dist/cli/commands/org-settings.d.ts

@@ -1,7 +1,8 @@
 /**
  * Org-settings management commands for kici-admin.
  *
- * Subcommand namespace: `kici-admin org-settings global-workflows <subcommand>`.
+ * Subcommand namespace: `kici-admin org-settings global-workflows <subcommand>`
+ * and `kici-admin org-settings dashboard-writes <subcommand>`.
  *
  * Talks to the orchestrator admin API directly (not the Platform dashboard
  * proxy), so the CLI stays operable even when Platform is unavailable. Backed

package/dist/cli/commands/shared/secret-input.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared input-mode helper for `kici-admin secret set` and
+ * `kici-admin variable set`.
+ *
+ * Resolves a value from exactly one of:
+ *   --value <plaintext>   — argv literal (warned; goes into shell history)
+ *   --prompt              — interactive no-echo prompt (TTY only)
+ *   --from-stdin          — pipe (full stdin until EOF)
+ *   --from-file <path>    — file contents (--trim default-on)
+ *   --from-env  <VAR>     — env var contents
+ *
+ * Default-mode resolution when no flag is provided:
+ *   TTY     -> --prompt
+ *   non-TTY -> --from-stdin
+ *
+ * Optional checks:
+ *   --confirm-fingerprint <hex>  — SHA-256 fingerprint guard against
+ *     paste corruption.
+ *
+ * The helper does NOT print to stdout (it returns the value). It DOES
+ * write to stderr for the `--value` warning, the prompt label, and any
+ * "empty value" warning. Stdout is reserved for the caller's confirmation
+ * output so the caller's `--dry-run` summary stays clean.
+ */
+export interface SecretInputOptions {
+    value?: string;
+    fromStdin?: boolean;
+    fromFile?: string;
+    fromEnv?: string;
+    prompt?: boolean;
+    trim?: boolean;
+    confirmFingerprint?: string;
+}
+export interface SecretInputResult {
+    value: string;
+    /** Which input mode supplied the value (after default resolution). */
+    source: 'value' | 'stdin' | 'file' | 'env' | 'prompt';
+}
+export declare function resolveSecretInput(opts: SecretInputOptions, stderr?: NodeJS.WritableStream, stdin?: NodeJS.ReadStream): Promise<SecretInputResult>;
+/**
+ * Compute the canonical SHA-256 fingerprint for a value. Helper for
+ * callers (tests, --dry-run output) that want to display the same hex
+ * the user would pass to `--confirm-fingerprint`.
+ */
+export declare function fingerprintValue(value: string): string;
+//# sourceMappingURL=secret-input.d.ts.map

package/dist/cli/commands/variable.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Environment variable management commands for kici-admin.
+ *
+ *   kici-admin variable list   <orgId> <environment>
+ *   kici-admin variable get    <orgId> <environment> <key>
+ *   kici-admin variable set    <orgId> <environment> <key> [--value | --from-stdin | --from-file | --from-env | --prompt]
+ *   kici-admin variable delete <orgId> <environment> <key>
+ *
+ * Org-level environment variables are plaintext-at-rest in the
+ * orchestrator's DB; the dashboard write path is gated by the
+ * `variables.set` / `variables.delete` switches in the dashboard-write
+ * policy. This CLI is the always-available authority path when the
+ * dashboard is disabled for either switch.
+ */
+import type { Command } from 'commander';
+import type { AdminApiClient } from '../api-client.js';
+export declare function registerVariableCommands(program: Command, getClient: () => AdminApiClient): void;
+//# sourceMappingURL=variable.d.ts.map

package/dist/cli/service/index.d.ts

@@ -9,6 +9,7 @@
 export type { ServiceManager, ServiceConfig, ServiceStatus, ServiceState, ServicePlatform, RestartPolicy, LogOptions, } from './types.js';
 export { DEFAULT_RESTART_POLICY } from './types.js';
 export { detectPlatform, isRoot, getConfigDir, getLogDir, getCacheDir } from './platform-detect.js';
+export { resolveUserLevel, type PrivilegeOpts } from './privilege.js';
 import type { ServiceManager, ServicePlatform } from './types.js';
 /**
  * Create a ServiceManager for the given platform.

package/dist/cli/service/launchd.d.ts

@@ -22,6 +22,25 @@ export declare class LaunchdServiceManager implements ServiceManager {
      * Visible for testing.
      */
     generatePlist(config: ServiceConfig): string;
+    /**
+     * Resolve the launchctl domain string for a service config.
+     *
+     *   - User-level (LaunchAgent at `~/Library/LaunchAgents/…`) → `gui/<uid>`
+     *   - System-level (LaunchDaemon at `/Library/LaunchDaemons/…`) → `system`
+     *
+     * The legacy `launchctl load` / `unload` verbs implicitly inferred the
+     * domain from the plist's filesystem location, but they fail silently on
+     * headless macOS hosts where no GUI session exists (the `gui/<uid>` domain
+     * is not available without a console login). The modern `bootstrap` /
+     * `bootout` / `kickstart` / `kill` verbs take the domain explicitly, so a
+     * system-level LaunchDaemon loads regardless of whether anyone is logged
+     * in at the console — exactly what we need for headless deploy targets.
+     */
+    private domain;
+    /** `<domain>/<label>` — the target string for kickstart/kill/print/enable. */
+    private domainTarget;
+    /** Is the service currently loaded in its target domain? */
+    private isLoaded;
     install(config: ServiceConfig): Promise<void>;
     uninstall(config: ServiceConfig): Promise<void>;
     start(config: ServiceConfig): Promise<void>;

package/dist/cli/service/privilege.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Resolve the system-vs-user privilege level for a service lifecycle command.
+ *
+ * Five CLI verbs (install / start / stop / restart / uninstall) need to agree
+ * on whether they're operating against the user-level service
+ * (~/Library/LaunchAgents, `systemctl --user`) or the system-level one
+ * (/Library/LaunchDaemons, `systemctl`). Default behavior (no flag) is to
+ * auto-detect based on UID — non-root → user-level, root → system-level.
+ *
+ * Explicit `--system` / `--user-level` flags override the auto-detect.
+ * They're mutually exclusive: passing both throws. Passing `--system`
+ * without root throws with an actionable "re-run under sudo" message.
+ */
+export interface PrivilegeOpts {
+    /** Force system-level install/lifecycle. Requires root. */
+    system?: boolean;
+    /** Force user-level install/lifecycle. */
+    userLevel?: boolean;
+}
+export declare function resolveUserLevel(opts: PrivilegeOpts): boolean;
+//# sourceMappingURL=privilege.d.ts.map

package/dist/cli/wizard/orchestrator-wizard.d.ts

@@ -11,6 +11,7 @@ interface OrchestratorInstallConfig {
     databaseUrl: string;
     port: number;
     secretsKey: string;
+    bootstrapAdminToken: string;
     platformUrl?: string;
     platformToken?: string;
     /** Source to add after orchestrator is running. */
@@ -30,8 +31,9 @@ interface OrchestratorInstallConfig {
  * 2. Database URL
  * 3. Port
  * 4. Secrets encryption key
- * 5. Platform URL + token (if platform/hybrid mode)
- * 6. Webhook secret (if hybrid/independent mode)
+ * 5. Bootstrap admin token (for kici-admin authentication)
+ * 6. Platform URL + token (if platform/hybrid mode)
+ * 7. Webhook secret (if hybrid/independent mode)
  */
 export declare function runOrchestratorWizard(): Promise<OrchestratorInstallConfig>;
 export {};