@kici-dev/orchestrator 0.12.0 → 0.14.0

package/dist/pipeline/changed-files.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The one changed-files resolver every dispatch path calls: same-source, the
+ * no-lock-file organization-wide pass, cross-source repo mode, and rerun.
+ *
+ * `unavailable` means the orchestrator holds no authoritative list; whether the
+ * agent can compute one is the range's question, answered by `resolveDiffRange`.
+ */
+import { type ChangedFilesStatus, type DiffRange, type LockWorkflow, type SimulatedEvent, type WebhookNormalizer, type WorkflowDecision } from '@kici-dev/engine';
+import type { ProviderBundle } from '../provider-registry.js';
+export interface ResolvedChangedFiles {
+    files: string[];
+    status: ChangedFilesStatus;
+    range: DiffRange;
+}
+/**
+ * Resolve the files an event changed through a bundle's fetcher.
+ *
+ * - no workflow in `workflows` has a `paths` trigger → `skipped`;
+ * - a deleted branch → `fetched` + `[]`, whichever provider delivered it;
+ * - no fetcher, or a fetcher that throws → `unavailable`, never a failed delivery.
+ */
+export declare function resolveEventChangedFiles(args: {
+    bundle: Pick<ProviderBundle, 'changedFilesFetcher'>;
+    credentials: unknown;
+    repoIdentifier: string;
+    eventName: string;
+    payload: unknown;
+    event: SimulatedEvent;
+    /** Omitted: always resolve — a re-evaluation has no lock file to consult. */
+    workflows?: readonly LockWorkflow[];
+}): Promise<ResolvedChangedFiles>;
+/**
+ * Stamp the repository's default branch on a normalized event, so the
+ * new-branch range (`resolveDiffRange`) and the agent that receives this event
+ * read the same value. `extractDefaultBranch` prefers the normalizer's hook,
+ * which covers GitLab's `project.default_branch`.
+ */
+export declare function withDefaultBranch(event: SimulatedEvent, payload: unknown, normalizer: WebhookNormalizer): SimulatedEvent;
+/** Copy a resolved list and its status onto the event the matcher reads. */
+export declare function stampChangedFiles(event: SimulatedEvent, resolved: ResolvedChangedFiles): SimulatedEvent;
+/**
+ * Downgrade a cross-source pull-request deferral to a conservative match.
+ *
+ * A cross-source job checks out the registration's commit, never the pull
+ * request's head, so no agent can diff the pull request for it. A path
+ * decision the orchestrator could not make therefore runs the workflow, as a
+ * range-less push does, instead of handing the agent a diff of the wrong
+ * commits. Push ranges diff explicit commits and keep their deferral.
+ */
+export declare function withoutCrossSourcePrDeferral(decision: WorkflowDecision, event: SimulatedEvent): WorkflowDecision;
+//# sourceMappingURL=changed-files.d.ts.map

package/dist/pipeline/cross-source-tally.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A generic delivery can run both halves — cross-source for other sources'
+ * registrations, and the inbound source's own lock when its normalizer reads a
+ * repository. The delivery still gets one event-log row: the same-source path
+ * writes it, and this wrapper folds the cross-source half into it.
+ */
+import type { ProcessingDeps } from './processor.js';
+export interface CrossSourceTally {
+    candidatesConsidered: number;
+    jobsDispatched: number;
+    /** A cross-source candidate evaluated `paths` against an unavailable diff. */
+    degraded: boolean;
+}
+/**
+ * Wrap `deps.eventLog` so whichever row the same-source path records — corrupt
+ * lock, missing lock, skip or processed — also counts the cross-source half's
+ * dispatched jobs and carries its degraded reason. A reason the same-source
+ * path already set wins.
+ */
+export declare function withCrossSourceTally(deps: ProcessingDeps, tally: CrossSourceTally): ProcessingDeps;
+//# sourceMappingURL=cross-source-tally.d.ts.map

package/dist/pipeline/degraded-reason.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Annotation written to a `processed` event-log row when path filters were
+ * evaluated against an unavailable changed-files diff. Reuses the existing
+ * free-text field so the outcome is never a silent `processed / matched 0` —
+ * no new event-log status enum value is added.
+ */
+export declare const DEGRADED_CHANGED_FILES_REASON = "trigger evaluation degraded: changed files unavailable \u2014 path filters matched conservatively";
+//# sourceMappingURL=degraded-reason.d.ts.map

package/dist/pipeline/dispatch-matched-workflow.d.ts

@@ -704,6 +704,8 @@ export declare function materializeStaticJobsSafe(staticJobs: readonly LockJob[]
     expansionMap: Map<string, readonly string[]>;
     matrixFailures: RejectedJob[];
 }>;
+/** The `paths` lists this workflow's matching left to the agent, or undefined. */
+export declare function deferredPathsOf(ctx: Pick<WorkflowDispatchContext, 'decision'>): string[][] | undefined;
 /**
  * Scan a lock workflow's always-mode approval timeouts (workflow-level +
  * each static job) for a non-positive / non-finite `timeoutSeconds`. Returns the
@@ -879,6 +881,8 @@ export declare function catchUpNeedsGatedJobs(args: {
 }): Promise<void>;
 /** Why an init result must not lead to a dispatch. */
 export declare enum InitDispatchSuppression {
+    /** The agent's clone diff matched none of the deferred `paths`. */
+    Paths = "paths",
     /** The workflow's own `filter` decided the workflow does not apply. */
     Filter = "filter",
     /** The job is already rejected by a context rule, or held for approval. */
@@ -887,6 +891,11 @@ export declare enum InitDispatchSuppression {
 /**
  * Decide whether an arrived init result may dispatch its job.
  *
+ * `Paths` is checked first: a workflow whose deferred `paths` did not match
+ * never triggered, whatever its filter says. Only an explicit `false`
+ * suppresses — an agent that predates deferred paths reports no verdict, and
+ * that absence dispatches.
+ *
  * `Filter` requires the workflow to actually declare a filter as well as the
  * agent to have reported `false`: a buggy or rogue agent must not be able to
  * suppress a filter-less workflow by inventing the field, and an agent that
@@ -917,6 +926,7 @@ export declare enum InitDispatchSuppression {
  */
 export declare function initDispatchSuppression(workflow: Pick<LockWorkflow, 'hasFilter'>, initResult: {
     filterPassed?: boolean;
+    pathsPassed?: boolean;
 }, jobEnvData: Pick<JobEnvData, 'rejected' | 'held'>): InitDispatchSuppression | null;
 export interface GeneratedJobConfig {
     /**

package/dist/pipeline/global-eval-round.d.ts

@@ -87,8 +87,9 @@ export declare function hasDeferredGenerator(lockEntry: LockWorkflow): boolean;
  * those that must go through an eval round first.
  *
  * A candidate needs the round when it declares a `filter` (only the agent may
- * run the predicate) or carries a needs-free `DynamicJobFn` (only the agent may
- * run the generator, and it depends on nothing the run produces). Everything
+ * run the predicate), carries a needs-free `DynamicJobFn` (only the agent may
+ * run the generator, and it depends on nothing the run produces), or matched
+ * with deferred `paths` (only the agent's clone holds the diff). Everything
  * else — static jobs, and result-aware generators the run evaluates later — is
  * handed to the dispatch pipeline as declared, so routing it through a round
  * would add a job dispatch and an agent round trip for nothing.

package/dist/pipeline/processor.d.ts

@@ -49,6 +49,8 @@ import type { RegistrationIndex } from '../registration/registration-index.js';
 import type { CronScheduler } from '../cron/cron-scheduler.js';
 import type { GlobalWorkflowPolicy } from '../security/global-workflow-policy.js';
 import type { EventLogWriter } from '../webhook/event-log.js';
+/** The one event-log method the pipeline calls; a per-delivery wrapper can stand in for the writer. */
+export type EventLogRecorder = Pick<EventLogWriter, 'record'>;
 import { EventLogSource } from '@kici-dev/engine';
 import type { LockJob } from '@kici-dev/engine';
 import type { ContextStore } from '../contexts/context-store.js';
@@ -203,6 +205,12 @@ export declare function resolveLockFileWithFallback(args: {
     registrationIndex: RegistrationIndex | undefined;
     lockFileCache: LockFileCache;
     deliveryId: string;
+    /**
+     * False when cross-source repo mode already evaluated this delivery's
+     * other-source registrations for the same repository: the fallback would
+     * re-read exactly those registrations. Defaults to true.
+     */
+    allowRegistrationFallback?: boolean;
 }): Promise<{
     lockFile: FullLockFile | null;
     resolvedVia: 'inbound' | 'fallback' | 'miss' | 'corrupt';
@@ -476,7 +484,7 @@ export interface ProcessingDeps {
     /** Global workflow policy for org-level permission enforcement. Optional -- if not set, global workflows are unrestricted. */
     globalWorkflowPolicy?: GlobalWorkflowPolicy;
     /** Inbound webhook delivery log writer. Optional -- if not set, deliveries are not persisted to event_log. */
-    eventLog?: EventLogWriter;
+    eventLog?: EventLogRecorder;
     /** Where this delivery arrived: 'relay' (Platform WS) or 'direct' (HTTP).
      *  Used by the eventLog writer to populate the source column. Defaults to
      *  'direct' when omitted (independent / direct paths). */

package/dist/pipeline/rerun-inputs.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Inputs every re-run path rebuilds from an original run: its stored webhook
+ * payload, the provider binding its row records, the delivery's event name, the
+ * normalized event, and its changed files. Shared by the per-repository re-run,
+ * the evaluation-round re-run and release, and the cross-repository global
+ * re-run, so the paths cannot disagree about how a run's inputs are read back.
+ */
 import type { SimulatedEvent } from '@kici-dev/engine';
 import type { ProviderRegistry } from '../provider-registry.js';
 import type { TrustPolicyOutcome } from '../security/trust-policy-gate.js';
@@ -59,7 +66,9 @@ export declare function loadDeliveryEventName(originalRun: OriginalRunRow, deps:
 /** The verdict an approved security hold stands for. */
 export declare const RELEASED_DECISION: TrustPolicyOutcome;
 /**
- * The normalized form of the delivery the round was deciding.
+ * The normalized form of the delivery the round was deciding, stamped with the
+ * repository's default branch as the delivery stamped it: the jobs a re-run
+ * dispatches carry this event, and an agent derives a new-branch diff from it.
  *
  * Read-only, and it throws — so it runs before the requestId claim, never
  * inside the re-evaluation.
@@ -69,13 +78,13 @@ export declare function normalizeRoundEvent(originalRun: OriginalRunRow, provide
     action: string | null;
 }, payload: Record<string, unknown>, refusal?: RerunRefusal): SimulatedEvent;
 /**
- * Stamp the re-evaluated event with the source repository's changed files.
+ * Stamp the re-evaluated event with the source repository's default branch and
+ * changed files.
  *
- * Unconditional, unlike the delivery path's fetch: that path skips the fetch
- * when no trigger in the source repo's lock file uses path patterns, and a
- * scoped re-evaluation has no such lock file to read. An error carries
- * `unavailable`, which every path filter downstream already treats
- * conservatively.
+ * The resolve is unconditional: the delivery path skips it when no trigger in
+ * the source repo's lock file uses path patterns, and a scoped re-evaluation
+ * has no such lock file to bound it. A bundle with no fetcher, or a fetch
+ * error, carries `unavailable`.
  */
 export declare function withChangedFiles(opts: {
     event: SimulatedEvent;

package/dist/providers/github/changed-files.d.ts

@@ -28,10 +28,15 @@ export declare function withRateLimitRetry<T>(fn: () => Promise<T>, context: str
 /**
  * GitHub-specific implementation of ChangedFilesFetcher.
  *
- * For PRs: uses paginated pulls.listFiles API (handles up to 3000 files).
- * For pushes: uses repos.compareCommits API (logs warning at 300+ files).
- * For initial pushes (zero SHA): returns empty array.
- * For unknown events: returns empty array.
+ * For PRs: uses the paginated pulls.listFiles API; a result at GitHub's
+ * 3000-file cap is truncated, so it reports `unavailable`.
+ * For pushes: uses the repos.compareCommits API; a result at GitHub's 300-file
+ * cap is truncated, so it reports `unavailable`.
+ * For a new branch (zero `before`): compares the default branch against
+ * `after` (three-dot), the files the branch adds. With no known default
+ * branch, or the default branch itself being created, it reports `unavailable`.
+ * For a deleted branch (zero `after`): `fetched` + [].
+ * For unknown events: reports `unavailable`.
  */
 export declare class GitHubChangedFilesFetcher implements ChangedFilesFetcher {
     private readonly config;
@@ -55,5 +60,10 @@ export declare class GitHubChangedFilesFetcher implements ChangedFilesFetcher {
      * Get changed files for a push event using compareCommits API.
      */
     private getPushChangedFiles;
+    /**
+     * Compare two refs through the compareCommits API. A result at GitHub's
+     * 300-file cap is truncated, so it reports `unavailable`.
+     */
+    private compare;
 }
 //# sourceMappingURL=changed-files.d.ts.map

package/dist/providers/universal-git/changed-files.d.ts

@@ -8,6 +8,10 @@
  * `commits[].{added,modified,removed}` arrays in the push payload, so we
  * extract them via JSONPath from the already-delivered webhook body.
  *
+ * Forges cap `commits[]`. A preset whose forge sends a total commit count
+ * (`commitsTotal`) or has a documented list cap (`commitsCap`) reports a
+ * truncated push as `unavailable` rather than a partial list.
+ *
  * 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
@@ -38,6 +42,8 @@ export declare class UniversalGitChangedFilesFetcher implements ChangedFilesFetc
      * @param _credentials    Unused — no REST call is made.
      */
     getChangedFiles(_repoIdentifier: string, eventType: string, payload: unknown, _credentials: unknown): Promise<ChangedFilesResult>;
+    /** Whether the payload lists fewer commits than the push carried. */
+    private isTruncated;
     private classifyEvent;
 }
 //# sourceMappingURL=changed-files.d.ts.map

package/dist/providers/universal-git/config.d.ts

@@ -73,6 +73,8 @@ export declare const UniversalGitPayloadPathsSchema: z.ZodObject<{
     commitsModified: z.ZodString;
     commitsRemoved: z.ZodString;
     commitMessage: z.ZodOptional<z.ZodString>;
+    commitsTotal: z.ZodOptional<z.ZodString>;
+    commitsCap: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type UniversalGitPayloadPaths = z.infer<typeof UniversalGitPayloadPathsSchema>;
 /**
@@ -131,6 +133,8 @@ export declare const UniversalGitConfigSchema: z.ZodObject<{
         commitsModified: z.ZodString;
         commitsRemoved: z.ZodString;
         commitMessage: z.ZodOptional<z.ZodString>;
+        commitsTotal: z.ZodOptional<z.ZodString>;
+        commitsCap: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     eventMapping: z.ZodOptional<z.ZodObject<{
         push: z.ZodArray<z.ZodString>;

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

@@ -74,6 +74,16 @@ interface ReplaceAllOptions {
     depCacheKey?: DepCacheKey;
     /** Set of workflow names that should be marked as global */
     globalWorkflowNames?: Set<string>;
+    /**
+     * Delete this routing key's rows for the repo whose workflow the incoming set
+     * does not name. `true` (the default) is the default-branch push sync: the
+     * lock file is the whole truth for the repo. The manual registration route
+     * passes `false`: it upserts the workflows it names and leaves every other
+     * registration of the repo alone, which is what
+     * `kici-admin workflow register-manual` documents and what its direct-DB
+     * mode does.
+     */
+    prune?: boolean;
 }
 /**
  * DB CRUD for workflow_registrations table with atomic upsert-based replace-all.

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

@@ -4,7 +4,9 @@
  * 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.
+ * stays operable even when Platform is unavailable. `GET
+ * /api/v1/admin/cluster-settings/propagation` reports which settings version
+ * each orchestrator this coordinator knows has applied.
  *
  * These knobs are fleet-wide, not per-tenant, so the route is deliberately NOT
  * under `/orgs/:customerId/*`. Mutations require the `secret.write` RBAC
@@ -15,9 +17,19 @@ import { Hono } from 'hono';
 import { type Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+import type { PeerRegistry } from '../cluster/peer-registry.js';
+/** The live view behind `GET /cluster-settings/propagation`. */
+export interface ClusterSettingsPropagationSource {
+    instanceId: string;
+    peerRegistry: Pick<PeerRegistry, 'getAllPeers'>;
+    /** The cluster-settings version this coordinator's reads currently serve. */
+    localVersion: () => number;
+}
 interface ClusterSettingsRouteDeps {
     db: Kysely<Database>;
     rbac: RbacEnforcer;
+    /** Mounts `GET /cluster-settings/propagation` when set. */
+    propagation?: ClusterSettingsPropagationSource;
 }
 type AdminEnv = {
     Variables: {

package/dist/routes/admin-event-inspect.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Admin API routes for inspecting internal events (`kici_events`).
+ *
+ *   GET /api/v1/admin/events      — list events, newest first (name, outcome, time filters)
+ *   GET /api/v1/admin/events/:id  — one event: its payload and the runs it dispatched
+ *
+ * Each row carries its dispatch state (`pending`, `leased`, `retrying`,
+ * `processed`, `dlq`) and, once processed, how the router resolved it
+ * (`matched`, `no-target-repo`, …) with the number of workflows it reached.
+ * Both routes need `event_dlq.read`, the permission that already gates reading
+ * `kici_events` rows; the payload on `show` also needs
+ * `event_log.read_payload`. A routing-key-scoped token sees only events
+ * emitted under its own key.
+ */
+import { Hono } from 'hono';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { EventStore } from '../events/event-store.js';
+import type { TokenManager } from '../secrets/token-manager.js';
+import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+export interface AdminEventInspectRoutesDeps {
+    db: Kysely<Database>;
+    eventStore: EventStore;
+    tokenManager: TokenManager;
+    rbac: RbacEnforcer;
+}
+type AdminEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
+export declare function createAdminEventInspectRoutes(deps: AdminEventInspectRoutesDeps): Hono<AdminEnv>;
+export {};
+//# sourceMappingURL=admin-event-inspect.d.ts.map

package/dist/routes/admin-peer-forget.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Forget a departed peer, behind `kici-admin peer forget <instance-id>`.
+ *
+ * Mounted inside `createAdminRoutes` at `/api/v1/admin`, so the Bearer-token
+ * auth middleware has already resolved the caller's role. Needs an unscoped
+ * token and the `peer.manage` permission (owner, admin).
+ *
+ * - `POST /api/v1/admin/peers/forget { instanceId, timeoutMs? }` — drop the
+ *   peer from this coordinator's live peer registry, then from every connected
+ *   sibling coordinator's, and answer with one result per coordinator.
+ *
+ * Forgetting never touches the peer's credential (`kici-admin peer revoke`
+ * refuses its next connection). A peer that connects again later is
+ * registered again as usual.
+ */
+import { Hono } from 'hono';
+import type { AccessLogWriter } from '../audit/access-log.js';
+import { type PeerForgetResult } from '../cluster/peer-forget.js';
+import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+type AdminEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
+/** What the route needs from the coordinator it runs on. */
+export interface PeerForgetRouteDeps {
+    /**
+     * Forget `instanceId` here, then on every connected sibling coordinator
+     * (skipped when this coordinator keeps the peer). The first result is this
+     * coordinator's. `acknowledgeBackstop` lets a forget that switches an
+     * event-provision backstop back on go ahead.
+     */
+    forget: (instanceId: string, timeoutMs: number, acknowledgeBackstop: boolean) => Promise<PeerForgetResult[]>;
+}
+export declare function createPeerForgetRoutes(deps: {
+    peerForget: PeerForgetRouteDeps;
+    rbac: RbacEnforcer;
+    accessLog?: AccessLogWriter;
+}): Hono<AdminEnv>;
+export {};
+//# sourceMappingURL=admin-peer-forget.d.ts.map

package/dist/routes/admin-scaler-orphans.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Live orphaned Firecracker VM admin routes, behind `kici-admin scaler orphans`.
+ *
+ * Mounted inside `createAdminRoutes` at `/api/v1/admin`, so the Bearer-token
+ * auth middleware has already resolved the caller's role. Both routes need an
+ * unscoped token: a VM belongs to a host, not to one routing key.
+ *
+ * - `GET  /api/v1/admin/scaler/orphans?target=<instance-id>&timeoutMs=<n>` —
+ *   every live Firecracker VM on the node, with how it is tracked
+ *   (`scaler.read`).
+ * - `POST /api/v1/admin/scaler/orphans/stop { target?, vmIds, timeoutMs? }` —
+ *   stop the approved VMs nothing tracks (`scaler.manage`).
+ *
+ * The node is this coordinator, or the peer `target` names, reached over the
+ * authenticated peer channel. The coordinator adds the one tracker only it
+ * can answer — a non-terminal job in its dispatch queue bound to the VM's
+ * agent — and never forwards a bound VM to the node's stop.
+ */
+import { Hono } from 'hono';
+import { type PeerScalerOrphansResponse } from '@kici-dev/engine';
+import type { AccessLogWriter } from '../audit/access-log.js';
+import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+import { type ScalerOrphansAnswer, type ScalerOrphansRequest } from '../scaler/orphan-requests.js';
+import { ScalerOrphansForwardFailure } from '../cluster/scaler-orphans-peer.js';
+type AdminEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
+/** What the routes need from the coordinator they run on. */
+export interface ScalerOrphansRouteDeps {
+    /** This coordinator's instance id. */
+    instanceId: string;
+    role: 'coordinator' | 'worker';
+    /** The cluster role a connected peer registered with, if known. */
+    peerRole: (instanceId: string) => 'coordinator' | 'worker' | undefined;
+    /** Answer from this coordinator's own host and tracking. */
+    answerLocal: (req: ScalerOrphansRequest) => Promise<ScalerOrphansAnswer>;
+    /** Forward to a peer over the peer channel. */
+    forward: (target: string, req: ScalerOrphansRequest, timeoutMs: number) => Promise<PeerScalerOrphansResponse | ScalerOrphansForwardFailure>;
+    /** Non-terminal dispatch-queue jobs bound to these agent ids, keyed by agent id. */
+    findBindings: (agentIds: string[]) => Promise<Map<string, string>>;
+    /**
+     * The cluster instance each of these agent ids is registered with — this
+     * coordinator or a peer whose heartbeat lists it — keyed by agent id. An
+     * agent can register with an HA sibling of the node that runs its VM.
+     */
+    findRegistrations: (agentIds: string[]) => Map<string, string>;
+    /**
+     * The coordinator peers this cluster expects but has no live link to. Their
+     * registered agents are unknown, so while any is missing no VM can be shown
+     * to be untracked.
+     */
+    disconnectedCoordinators: () => string[];
+}
+export declare function createScalerOrphansRoutes(deps: {
+    orphans: ScalerOrphansRouteDeps;
+    rbac: RbacEnforcer;
+    accessLog?: AccessLogWriter;
+}): Hono<AdminEnv>;
+export {};
+//# sourceMappingURL=admin-scaler-orphans.d.ts.map

package/dist/routes/admin.d.ts

@@ -18,6 +18,9 @@ import type { AgentRegistry } from '../agent/registry.js';
 import type { SharedConfigStore } from '../config/shared-store.js';
 import type { ResolvedMasterKeys } from '../secrets/config.js';
 import { type HeldRunReleaseWiring } from './admin-held-runs.js';
+import { type ClusterSettingsPropagationSource } from './admin-cluster-settings.js';
+import { type ScalerOrphansRouteDeps } from './admin-scaler-orphans.js';
+import { type PeerForgetRouteDeps } from './admin-peer-forget.js';
 import type { DrainController } from '../drain/drain-controller.js';
 import type { SourceStore } from '../sources/source-store.js';
 import type { JoinTokenManager } from '../cluster/join-token.js';
@@ -159,6 +162,26 @@ export interface AdminRouteDeps {
      * write is best-effort, never gating.
      */
     accessLog?: AccessLogWriter;
+    /**
+     * Optional -- the coordinator's live-VM listing and stop, for this node or a
+     * `--target` peer. Backs `GET /api/v1/admin/scaler/orphans` and
+     * `POST /api/v1/admin/scaler/orphans/stop` (`kici-admin scaler orphans`).
+     * Bound by orchestrator-core once the cluster is up.
+     */
+    scalerOrphans?: ScalerOrphansRouteDeps;
+    /**
+     * Optional -- forget a departed peer here and on every connected sibling
+     * coordinator. Backs `POST /api/v1/admin/peers/forget` (`kici-admin peer
+     * forget`). Bound by orchestrator-core once the cluster is up.
+     */
+    peerForget?: PeerForgetRouteDeps;
+    /**
+     * Optional -- the peer view behind
+     * `GET /api/v1/admin/cluster-settings/propagation` (the propagation section of
+     * `kici-admin cluster-settings show`). Bound by orchestrator-core once the
+     * cluster is up; the route is not mounted without it.
+     */
+    clusterSettingsPropagation?: ClusterSettingsPropagationSource;
     /**
      * Optional -- fulfil deferred attestations on demand (mints in the running
      * orchestrator process, which owns the Platform WS). Backs

package/dist/scaler/backend-factory.d.ts

@@ -38,7 +38,12 @@ export interface BackendFactoryContext {
     tokenTtlMs?: number;
     /** Live per-spawn resolver for the fleet-wide agent-token TTL. */
     tokenTtlProvider: () => Promise<number>;
-    /** DB-backed on the leader, in-memory on the worker. */
+    /**
+     * Live per-spawn resolver for the fleet-wide Firecracker API-socket wait.
+     * A coordinator reads `cluster_settings`; a worker reads its pulled snapshot.
+     */
+    firecrackerApiSocketWaitMsProvider: () => Promise<number>;
+    /** DB-backed on a coordinator, in-memory on a worker. */
     ipAllocator: (params: IpAllocatorParams) => IpAllocator;
     /**
      * The already-constructed scaler state store. The event backend's claim

package/dist/scaler/bare-metal-backend.d.ts

@@ -2,7 +2,8 @@
  * Bare-metal scaler backend implementation.
  *
  * Manages ephemeral agent processes using child_process.spawn.
- * Uses detached process groups for clean killing of entire process trees.
+ * On Linux and macOS each agent leads its own process group, which teardown
+ * signals; on Windows teardown ends the agent's process tree with taskkill.
  * All agents are single-use: destroyed after job completion.
  */
 import { type ToolRequirement } from '@kici-dev/shared';
@@ -98,6 +99,11 @@ export declare class BareMetalScalerBackend implements ScalerBackend {
     get labelSets(): LabelSetConfig[];
     getActiveCount(): number;
     spawn(labelSet: string[], agentId: string, orchestratorUrl: string, onEvent?: ScalerEventCallback, effectiveLimits?: EffectiveLimits, spawnContext?: SpawnContext, signal?: AbortSignal): Promise<ManagedAgent>;
+    /**
+     * Record that the agent registered. From then on its exit is a disconnect
+     * the manager handles, not a failed spawn.
+     */
+    markRegistered(managedId: string): void;
     /**
      * Launch the agent inside the job's own container image.
      *
@@ -145,23 +151,19 @@ export declare class BareMetalScalerBackend implements ScalerBackend {
         entry?: ScalerEntry;
     }): ValidationResult;
     /**
-     * Build the (command, args) tuple used to spawn an agent process.
+     * End a Windows agent's whole process tree.
      *
-     * Two modes:
-     *   - Direct: returns (binaryPath, []) — the historical bare-metal flow.
-     *     Used when enforceCgroups is false, the host is non-Linux, or the
-     *     resolved limits carry no positive cpus/memBytes.
-     *   - systemd-run scope: returns ('systemd-run', [...]) wrapping the
-     *     binary in a transient `--user --scope --slice=kici-scaler` cgroup
-     *     with `CPUQuota=` / `MemoryMax=` properties translated from the
-     *     effective limits. The scope name embeds `agentId` so each agent is
-     *     a separately-named transient unit (and `systemctl --user status
-     *     kici-agent-<agentId>.scope` works).
+     * Windows has no process groups to signal and no SIGTERM, and Node.js cannot
+     * send a ctrl-C there (`process.kill` terminates the target unconditionally),
+     * so the tree is ended at once with `taskkill /T /F`. The pid is cmd.exe's, which runs the agent's `node` and
+     * everything it started.
      *
-     * `CPUQuota` is expressed as a percent (1.0 cpus = 100%). `MemoryMax`
-     * accepts a raw byte count.
+     * Nothing runs once Node.js has seen the child exit: libuv then releases its
+     * handle on the process, Windows may give the pid to an unrelated process,
+     * and `/T` would end that process's tree. While the child runs, the open
+     * handle keeps the pid ours.
      */
-    private buildSpawnInvocation;
+    private endWindowsTree;
     /**
      * Wait for a process to exit within a timeout.
      * Returns true if the process exited, false if timed out.