@kici-dev/orchestrator 0.11.0 → 0.13.0

package/dist/__test-helpers__/mock-db-query.d.ts

@@ -1,12 +1,11 @@
 /**
  * Predicate + projection evaluation for the shared `createMockDb` harness.
  *
- * Kept BYTE-IDENTICAL in two places —
- * `packages/orchestrator/src/__test-helpers__/mock-db-query.ts` and
- * `packages/platform/src/__test-helpers__/mock-db-query.ts`. Each package owns an
+ * Kept BYTE-IDENTICAL in the orchestrator and the Platform, which each carry a
+ * copy. Each package owns an
  * independent `createMockDb` builder and neither package may import the other, so
- * the evaluator is duplicated rather than shared. `mock-db-mirror.test.ts` in both
- * packages fails the moment the copies diverge.
+ * the evaluator is duplicated rather than shared. A drift test fails the moment
+ * the copies diverge.
  *
  * `createMockDb` used to return its configured rows verbatim, whatever the
  * query asked for: a `.where(...)` or a `.select([...])` was recorded on a spy

package/dist/agent/agent-version.d.ts

@@ -4,8 +4,8 @@
  * An agent reports its own package version in `agent.register`
  * (`agentRegisterSchema.version`), and the field is optional — an agent old
  * enough to omit it predates every feature this module gates on. The
- * orchestrator and the agent are deployed and upgraded independently
- * (`.claude/rules/compatibility.md`), so a feature the orchestrator ships is
+ * orchestrator and the agent are deployed and upgraded independently,
+ * so a feature the orchestrator ships is
  * routinely dispatched to a fleet that cannot run it, and the version is the
  * only fact the orchestrator has about what the fleet understands.
  */
@@ -16,9 +16,9 @@ type VersionBase = [number, number, number];
  * the string is not a version at all.
  *
  * The prerelease suffix is dropped rather than ordered because the suffixes in
- * play are build counters from the dev registry (`0.5.0-9159`), not semver
- * release candidates. Strict semver orders those BELOW `0.5.0`, which would
- * read every staging agent as too old for a feature it in fact carries.
+ * play are build counters (`0.5.0-9159`), not semver release candidates. Strict
+ * semver orders those BELOW `0.5.0`, which would read every agent on a
+ * prerelease build as too old for a feature it in fact carries.
  */
 export declare function parseVersionBase(version: string): VersionBase | null;
 /**

package/dist/agent/dispatcher.d.ts

@@ -258,6 +258,17 @@ export declare class Dispatcher {
          */
         hasPeerCoordinators?: () => boolean | Promise<boolean>;
     });
+    /** Runs with the ids of the jobs each disconnect triage failed; see {@link setDisconnectCleanup}. */
+    private disconnectCleanup?;
+    /**
+     * Install what runs with the ids of the jobs a disconnect triage failed. The
+     * agent WebSocket handler installs the release of their in-memory waiters
+     * (pending builds, inits, dynamic evaluations, global eval rounds). It runs
+     * inside {@link onAgentDisconnect}, so a path that drops an agent without
+     * waiting for its socket (heartbeat timeout, ack timeout, token revocation)
+     * reaches it too.
+     */
+    setDisconnectCleanup(cleanup: (failedJobIds: string[]) => void): void;
     /**
      * Dispatch a job to a matching agent, or queue it if none available.
      *
@@ -444,6 +455,32 @@ export declare class Dispatcher {
     private failRefusedDispatch;
     /** Free the slot and tracking a claim took on its agent; a claim for no agent took none. */
     private releaseClaimAccounting;
+    /**
+     * Release the slot and tracking `jobId` holds on `agentId`, if the job is
+     * still tracked there. Returns false when another path (a refusal, a
+     * put-back, a disconnect) already took it.
+     */
+    private releaseTrackedClaim;
+    /**
+     * Hand a job this coordinator just claimed from the queue to `agentId`,
+     * whose slot the claim took. A query that fails before the job is sent
+     * returns the claim ({@link returnUndeliveredClaim}) and rethrows, so the
+     * agent is not left holding a slot for a job it never received.
+     *
+     * @returns whether the job was sent.
+     */
+    private sendClaimedJob;
+    /**
+     * Put back a job a queue claim took but did not send: a query failed between
+     * the claim and the send. The agent's slot (and the job's tracking, once
+     * taken) is released so the agent takes work again, and the row returns to
+     * pending without spending a dispatch attempt, since no agent saw it. The
+     * next drain or the pending re-drive offers it again. A job a refusal or a
+     * disconnect already took is left to that path. If the put-back fails too,
+     * the row stays dispatched with no ack deadline and the stale-dispatch scan
+     * reaps it.
+     */
+    private returnUndeliveredClaim;
     /** Record that a job began executing on its agent. */
     markJobStarted(jobId: string): void;
     /**
@@ -482,6 +519,15 @@ export declare class Dispatcher {
      * triage finds nothing to double-handle.
      */
     private handleAckExpiry;
+    /**
+     * Drop an agent that did not acknowledge a dispatch. Its other in-flight jobs
+     * (a multi-slot agent may run more than the one that timed out) go through
+     * {@link onAgentDisconnect}, which reads the registration before its first
+     * await to tell a scaler-managed agent from a static one, so the triage
+     * starts first. The unregister right after removes the agent from routing at
+     * once, so a redispatch cannot re-select it while the triage awaits.
+     */
+    private dropUnacknowledgingAgent;
     /**
      * Handle an explicit dispatch rejection (`job.reject`) from an agent.
      * Undoes the dispatch accounting and requeues the job for another agent.
@@ -608,6 +654,8 @@ export declare class Dispatcher {
      * Used by the cancel-run API. Returns null if the job is not tracked (e.g. already completed).
      */
     getAgentIdForJob(jobId: string): string | null;
+    /** The jobs of `runId` this dispatcher currently tracks to an agent. */
+    getTrackedJobIdsForRun(runId: string): string[];
     /**
      * Start periodic cleanup of expired grace window entries.
      * Should be called during server startup.

package/dist/agent/registry.d.ts

@@ -117,7 +117,7 @@ export interface AgentEntry {
      * The `agent_tokens.id` row used to authenticate this connection, or
      * `null` when auth mode is `none`. Indexed by `tokenIdIndex` so a
      * synchronous revocation kick can enumerate every WS authenticated by
-     * a given token. in the pentest catalog.
+     * a given token.
      */
     tokenId: string | null;
     hostname: string | null;
@@ -240,10 +240,9 @@ export declare class AgentRegistry {
      *
      * Idempotent: re-scheduling the same tokenId is a no-op as long as
      * a timer is still queued — a token's `expires_at` doesn't shift
-     * across reconnects of the same agent. Closes the sister gap
-     * to the revocation finding (`agent-token-revocation-stale-ws`,
-     * fixed in `993bc3d9d`) where natural TTL expiration had no
-     * propagation path to in-flight WS connections.
+     * across reconnects of the same agent. Revocation kicks a token's
+     * in-flight WS connections at once; these timers do the same when
+     * the token reaches its natural TTL.
      */
     private readonly tokenExpiryTimers;
     /**
@@ -264,6 +263,37 @@ export declare class AgentRegistry {
      * registry behaves exactly as before.
      */
     constructor(deps?: AgentRegistryDeps);
+    /**
+     * Triages the in-flight jobs of an agent this registry drops on its own (a
+     * revoked or expired token): fails or requeues a scaler-managed agent's
+     * jobs, starts recovery for a static agent's. Installed by the dispatcher,
+     * which is built after the registry.
+     */
+    private disconnectTriage?;
+    /** Install the job triage {@link disconnectByTokenId} runs for each agent it drops. */
+    setDisconnectTriage(triage: (agentId: string) => Promise<unknown>): void;
+    /**
+     * Sockets whose `agent.register` is in flight (awaiting the scaler lookup),
+     * per agent id, with the id of the agent token each authenticated with
+     * (`null` without token auth). Kept here rather than in the WebSocket
+     * handler because the coordinator builds one handler per connection: a
+     * socket's close, and the check a registration makes against another agent
+     * token, must see a registration in flight on another connection.
+     */
+    private readonly registeringSockets;
+    /** Record that `ws`, authenticated with `tokenId`, has started registering `agentId`. */
+    beginRegistering(agentId: string, ws: WsLike, tokenId: string | null): void;
+    /** Record that `ws` has finished registering `agentId`, however it ended. */
+    endRegistering(agentId: string, ws: WsLike): void;
+    /** Whether a socket other than `ws` is registering `agentId` right now. */
+    isRegisteringElsewhere(agentId: string, ws: WsLike): boolean;
+    /**
+     * Whether another connection holds `agentId` under an agent token other than
+     * `tokenId`: the live registration, or a registration in flight on another
+     * socket. A registration without token auth (`null`) holds no token identity
+     * and conflicts with nothing.
+     */
+    isAgentIdHeldByOtherToken(agentId: string, tokenId: string, ws: WsLike): boolean;
     /**
      * Register an agent. If the agentId already exists, updates the existing
      * entry (agent reconnection scenario).
@@ -317,10 +347,9 @@ export declare class AgentRegistry {
      * Caller is the agent WS handler at register-time, when the token's
      * `agent_tokens.expires_at` column is non-null. Static tokens have
      * `expires_at = null` and are skipped at the call site (they have
-     * no TTL by design). Closes the sister gap to the revocation
-     * finding (`agent-token-revocation-stale-ws`, fixed in `993bc3d9d`)
-     * where natural TTL expiration had no propagation path to
-     * in-flight WS connections.
+     * no TTL by design). Revocation kicks a token's in-flight WS
+     * connections at once; this timer does the same at the token's
+     * natural TTL.
      */
     scheduleExpiryKick(tokenId: string, expiresAt: Date): void;
     /**

package/dist/agent-packaging/node-runtime-members.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The members of an official Node.js Linux or macOS archive that a KiCI payload
+ * vendors, relative to the archive's `node-v<version>-<os>-<arch>/` directory:
+ * the `node` binary, the `npm` and `npx` launchers, and the bundled npm package.
+ * With them in place, the agent's `resolveNpm()` finds
+ * `<nodeDir>/../lib/node_modules/npm/bin/npm-cli.js` beside the vendored `node`,
+ * so the builder role needs no npm on the host.
+ *
+ * This module has no imports so that repository tooling can read the list:
+ * `scripts/lib/node-dist.mjs` (the standalone package builder) keeps its own
+ * copy, and its test pins the two lists equal.
+ */
+export declare const NODE_RUNTIME_MEMBERS: readonly ['bin/node', 'bin/npm', 'bin/npx', 'lib/node_modules/npm'];
+//# sourceMappingURL=node-runtime-members.d.ts.map

package/dist/app.d.ts

@@ -10,7 +10,7 @@
  * - Request ID and logging middleware
  * - 25MB body size limit
  *
- * Pattern follows packages/platform/src/app.ts: returns { app, wss }.
+ * Same pattern as the Platform's app: returns { app, wss }.
  */
 import type { Kysely } from 'kysely';
 import type pg from 'pg';
@@ -41,6 +41,7 @@ import type { PendingInitTracker } from './cache/index.js';
 import type { PendingDynamicTracker, PendingGlobalEvalTracker } from './cache/index.js';
 import type { GlobalEvalRoundCache } from './cache/index.js';
 import type { CacheStorage } from './storage/types.js';
+import type { CacheUploadSettle } from './cache/cache-upload-settle.js';
 import type { ProvenanceTrustRoot } from './provenance/trust-root.js';
 import type { LocalSigner } from './oidc/local-dev-signer.js';
 import type { CheckRunReporter } from './reporting/check-run-reporter.js';
@@ -178,6 +179,11 @@ export interface AppDependencies {
     dispatchCacheRefs?: DispatchCacheRefTracker;
     /** Cache storage backend (S3) for metadata operations on upload completion. */
     cacheStorage?: CacheStorage;
+    /**
+     * In-flight build-cache publishes plus the per-org settle bound. Constructed
+     * once by orchestrator-core: the agent-WS factory below runs per connection.
+     */
+    cacheUploadSettle?: CacheUploadSettle;
     /** Provenance trust root used to verify build-provenance bundles at ingest. */
     provenanceTrustRoot?: ProvenanceTrustRoot;
     /**
@@ -197,7 +203,7 @@ export interface AppDependencies {
      */
     faultInjection?: import('./fault-injection-types.js').OrchestratorFaultInjection;
     /**
-     * Orchestrator-owned provenance signing (Phase 1 root of trust). Present when
+     * Orchestrator-owned provenance signing (the root of trust). Present when
      * `KICI_ORCHESTRATOR_PROVENANCE_ISSUER` is configured: the orchestrator mints +
      * signs identity tokens locally with its own ES256 key, and serves its own
      * OIDC discovery + JWKS + native verify endpoint. `resolveOrchestratorSigner`
@@ -342,7 +348,7 @@ export interface AppDependencies {
     globalWorkflowPolicy?: GlobalWorkflowPolicy;
     /** Inbound webhook delivery log writer. Optional -- if not set, deliveries are not persisted to event_log. */
     eventLogWriter?: EventLogWriter;
-    /** Cold-store handle (Phase E). Optional -- when present, admin event-log routes can serve archived rows. */
+    /** Cold-store handle. Optional -- when present, admin event-log routes can serve archived rows. */
     coldStore?: ColdStore | null;
     /** Read + mutation attribution log writer. Optional -- if not set, access_log rows are not written. */
     accessLogWriter?: AccessLogWriter;

package/dist/approvals/apply-decision.d.ts

@@ -50,7 +50,7 @@ export interface ApplyDecisionResult {
 export interface ApplyDecisionDeps {
     orgId: string;
     store: HeldRunStore;
-    /** Team name → member user ids (from the Plan-1 trust-policy cache). */
+    /** Team name → member user ids (from the trust-policy cache). */
     teamMembershipLookup: TeamMembershipLookup;
     /** Whether the run triggerer may self-approve (org_settings.allow_self_approval). */
     allowSelfApproval: boolean;

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

@@ -88,11 +88,10 @@ export declare class AccessLogWriter {
     recordInTransaction(executor: Kysely<Database> | Transaction<Database>, entry: AccessLogRecord): Promise<void>;
     private insert;
     /**
-     * Phase D: delegates to `loadAccessLogRange` so cold-store rows are
+     * Delegates to `loadAccessLogRange` so cold-store rows are
      * merged transparently when pagination crosses the warm cutoff. The
      * caller-visible `{items, nextCursor}` shape is preserved. NO
-     * --include-archived flag — access_log is "paginated/transparent"
-     * per design §7 row 11.
+     * --include-archived flag — access_log is "paginated/transparent".
      */
     query(filter: AccessLogQueryFilter): Promise<AccessLogQueryResult>;
     /**

package/dist/cache/cache-upload-settle.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Holding a build job's success until the cache publish its agent reported
+ * just before it has finished.
+ *
+ * A build agent sends `cache.upload.complete` and then, moments later, the
+ * build's terminal `job.status success`. The agent WebSocket handler runs
+ * frames concurrently, so without this record the success can release the
+ * jobs that wait on the build while the pointer naming the uploaded tarball is
+ * still being written — and they dispatch without the cache URL.
+ *
+ * The upload frame registers here before its first `await`. Frames enter the
+ * handler in wire order, so the registration is in place by the time the
+ * success frame is handled. The success then waits, bounded by the org's
+ * `cache_upload_settle_timeout_ms` (cluster default
+ * `KICI_CACHE_UPLOAD_SETTLE_TIMEOUT_MS`).
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+/** How a build success's wait for its cache publish ended. */
+export declare enum CacheUploadSettleOutcome {
+    /** No publish was in flight for the job. */
+    None = "none",
+    /** The effective timeout is 0: the wait is turned off. */
+    Disabled = "disabled",
+    /** Every in-flight publish finished, successfully or not. */
+    Settled = "settled",
+    /** The bound passed first. The publish may still finish afterwards. */
+    TimedOut = "timed-out"
+}
+/**
+ * The cache publishes in flight, per job. A full build registers two (the
+ * dependency tarball and the source tarball); a publish always settles —
+ * success or failure — so a waiter never sees a rejection.
+ */
+export declare class InFlightCacheUploads {
+    private readonly inFlight;
+    /** Register one publish for `jobId`; the returned function settles it (idempotent). */
+    begin(jobId: string): () => void;
+    has(jobId: string): boolean;
+    /** Number of jobs with a publish in flight. */
+    get size(): number;
+    /**
+     * Wait for every publish registered for `jobId` at call time, bounded by
+     * `timeoutMs`. A timeout leaves the records in place: they clear when their
+     * publishes settle.
+     */
+    waitFor(jobId: string, timeoutMs: number): Promise<CacheUploadSettleOutcome>;
+}
+/** What the agent WebSocket handler needs to hold a build's success. */
+export interface CacheUploadSettle {
+    uploads: InFlightCacheUploads;
+    /** The effective bound for the job's org (org override, else cluster default). */
+    timeoutMsFor: (orgId: string | undefined) => Promise<number>;
+}
+export interface CacheUploadSettleResult {
+    outcome: CacheUploadSettleOutcome;
+    timeoutMs?: number;
+    waitedMs?: number;
+}
+/**
+ * Wait for a job's in-flight cache publishes. Reads the setting only when a
+ * publish is in flight, so an ordinary job's success costs no query.
+ */
+export declare function awaitCacheUploadSettle(settle: CacheUploadSettle | undefined, job: {
+    jobId: string;
+    orgId: string | undefined;
+}): Promise<CacheUploadSettleResult>;
+/**
+ * Resolve the settle bound for an org: `org_settings.cache_upload_settle_timeout_ms`
+ * when set (0 included), otherwise `fallbackMs`. A missing DB, org, row or
+ * value, or a failed query, falls back — the caller is a frame handler that
+ * must not reject.
+ */
+export declare function createCacheUploadSettleTimeoutReader(db: Kysely<Database> | undefined, fallbackMs: number): (orgId: string | undefined) => Promise<number>;
+//# sourceMappingURL=cache-upload-settle.d.ts.map

package/dist/cache/pending-inits.d.ts

@@ -28,6 +28,15 @@ export interface InitResult {
      * explicit `false` suppresses.
      */
     filterPassed?: boolean;
+    /**
+     * Verdict on the workflow's deferred `paths`, reported only when the init job
+     * was asked to decide them. `false` means the agent's clone diff matched none
+     * of them and the job must not be dispatched.
+     *
+     * Optional on purpose: an agent that predates deferred paths never sends it,
+     * so absence means "no verdict" and dispatch proceeds.
+     */
+    pathsPassed?: boolean;
 }
 export declare class PendingInitTracker extends PendingTracker<InitResult> {
     constructor();

package/dist/cancel/cancel-run.d.ts

@@ -33,11 +33,12 @@ export interface CancelRunDeps {
      */
     instanceId?: string;
     /**
-     * Forward `job.cancel` to the coordinator holding the agent's socket.
-     * Returns whether the send left this process. Undefined ⇒ no peer transport,
-     * so a job owned by a sibling is unreachable rather than orphaned.
+     * Forward `job.cancel` to the coordinator holding the agent's socket, with
+     * `force` when the cancel is forced. Returns whether the send left this
+     * process. Undefined ⇒ no peer transport, so a job owned by a sibling is
+     * unreachable rather than orphaned.
      */
-    cancelJobOnPeer?: (peerId: string, runId: string, jobId: string, reason: string) => boolean;
+    cancelJobOnPeer?: (peerId: string, runId: string, jobId: string, reason: string, force?: boolean) => boolean;
     /** How stale a `cluster_instances` heartbeat may be and still read as live. */
     ownershipGraceMs?: number;
     /**
@@ -112,4 +113,21 @@ export declare class HeldRunCancelRefusedError extends Error {
  * returns a structured already-terminal result).
  */
 export declare function cancelRunWithReason(deps: CancelRunDeps, runId: string, reason: string, options?: CancelRunOptions): Promise<CancelRunResult>;
+/**
+ * Send `job.cancel` down this coordinator's own socket for the agent.
+ *
+ * Only an OPEN socket can receive it. A socket mid-close is still in the
+ * registry until its close handler unregisters it, and sending to it throws, so
+ * a non-OPEN socket leaves the job un-notified and the orphan sweep takes it.
+ * The send is wrapped so one bad socket cannot abort the whole cancellation and
+ * strand the run in `cancelling`.
+ */
+export declare function sendLocalCancel(args: {
+    registry: Pick<AgentRegistry, 'get'>;
+    runId: string;
+    jobId: string;
+    agentId: string | null;
+    reason: string;
+    force: boolean;
+}): boolean;
 //# sourceMappingURL=cancel-run.d.ts.map

package/dist/cancel/peer-job-cancel.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The receiving end of `peer.job.cancel`.
+ *
+ * A sibling forwards a cancel to the coordinator its agent is connected to,
+ * which it reads from the host roster. That coordinator's dispatcher tracks the
+ * job only when it dispatched or re-adopted it: an agent that reconnected here
+ * from a sibling, or one not yet back after this process restarted, is known
+ * only to `dispatch_queue.agent_id`. So the agent is resolved from the
+ * dispatcher first and from the dispatch record second, and a cancel that
+ * cannot be delivered is logged with the reason.
+ */
+import type { Kysely } from 'kysely';
+import { z } from 'zod';
+import type { PeerJobCancel } from '@kici-dev/engine';
+import type { Database } from '../db/types.js';
+import type { AgentRegistry } from '../agent/registry.js';
+import type { Dispatcher } from '../agent/dispatcher.js';
+export declare const PeerCancelOutcome: z.ZodEnum<{
+    "agent-not-connected": "agent-not-connected";
+    delivered: "delivered";
+    "lookup-failed": "lookup-failed";
+    "not-tracked": "not-tracked";
+}>;
+export type PeerCancelOutcome = z.infer<typeof PeerCancelOutcome>;
+/** A live dispatch row: the job and the agent it was handed to. */
+export interface DispatchedAgent {
+    jobId: string;
+    agentId: string | null;
+}
+export interface PeerCancelDelivery extends DispatchedAgent {
+    outcome: PeerCancelOutcome;
+}
+export interface PeerJobCancelDeps {
+    dispatcher: Pick<Dispatcher, 'getAgentIdForJob' | 'getTrackedJobIdsForRun'>;
+    registry: Pick<AgentRegistry, 'get'>;
+    /** The durable dispatch record. Absent on a worker, which has no database. */
+    lookupDispatched?: (runId: string, jobId: string | undefined) => Promise<DispatchedAgent[]>;
+    logger: {
+        info(message: string, meta?: object): unknown;
+        warn(message: string, meta?: object): unknown;
+    };
+}
+/** Read the live dispatch rows of a run, or of one job of it. */
+export declare function readDispatchedAgents(db: Kysely<Database>, runId: string, jobId: string | undefined): Promise<DispatchedAgent[]>;
+/**
+ * Deliver a `peer.job.cancel` to the agents connected here. Resolves; never
+ * rejects: every failure is an outcome and a warn line.
+ */
+export declare function deliverPeerJobCancel(deps: PeerJobCancelDeps, msg: PeerJobCancel): Promise<PeerCancelDelivery[]>;
+//# sourceMappingURL=peer-job-cancel.d.ts.map

package/dist/cancel/sweep-stuck-cancelling.d.ts

@@ -3,7 +3,9 @@ import type { Database } from '../db/types.js';
 export interface SweepStuckCancellingDeps {
     db: Kysely<Database>;
     /** The canonical cancel path, bound to this orchestrator's deps. */
-    cancelRun: (runId: string, reason: string) => Promise<unknown>;
+    cancelRun: (runId: string, reason: string, options: {
+        force: boolean;
+    }) => Promise<unknown>;
     /**
      * How long a run may sit in `cancelling` before it is re-driven. Twice the
      * recovery grace period: long enough that a graceful agent teardown finishes

package/dist/cli/commands/access-log.d.ts

@@ -2,9 +2,9 @@
  * Access log commands for kici-admin.
  *
  * Operator-facing read access to the orchestrator's access_log table
- * (read + mutation attribution with ActorPrincipal). Dogfood replacement
- * for raw psql when an operator asks "who read this run's payload last
- * Tuesday" or "show me everything a platform_operator actor did".
+ * (read + mutation attribution with ActorPrincipal). Use it instead of raw
+ * psql when an operator asks "who read this run's payload last Tuesday" or
+ * "show me everything a platform_operator actor did".
  *
  *   access-log list   List access-log rows with filters (cursor-paginated)
  *   access-log show   Show a single entry by id

package/dist/cli/commands/agent-service/agent-env.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The env file `kici-admin agent install` writes for a new agent. Each field
+ * lands in the variable the agent's config loader reads; that loader refuses
+ * any KICI_* variable it does not know, so a misspelt key here stops the agent
+ * at startup. `agent-env.test.ts` loads the rendered file through the agent's
+ * own loader to hold the two together.
+ */
+export interface AgentEnvFields {
+    /** First line of the file, a `#` comment naming what wrote it. */
+    header: string;
+    orchestratorUrl?: string;
+    token?: string;
+    /** Routing labels, written comma-separated. */
+    labels?: string[];
+    /** The agent's HTTP port; omitted, the agent uses its default. */
+    port?: number;
+}
+/** Render the env file, one `KEY=value` line per field that was given. */
+export declare function renderAgentEnvFile(fields: AgentEnvFields): string;
+//# sourceMappingURL=agent-env.d.ts.map

package/dist/cli/commands/agent-service/status.d.ts

@@ -1,9 +1,9 @@
 /**
  * `kici-admin agent status` command.
  *
- * Shows OS-level service status (state, PID, uptime) and queries
- * the running agent's health API for agent-specific info (labels,
- * orchestrator connection, current job).
+ * Shows OS-level service status (state, PID, uptime) and queries the
+ * running agent's `/health` endpoint for its ID, orchestrator connection,
+ * active job count, version, build fingerprint and uptime.
  *
  * Target resolution goes through resolveInstanceTarget — the same priority chain
  * every lifecycle command uses (--instance-dir > --name > CWD manifest >

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

@@ -6,7 +6,7 @@
  *                                   unverifiable rows; `--all` re-evaluates
  *                                   every row. Direct DB + object storage.
  *
- * Classified `kici-admin` (orchestrator DB plane) per .claude/rules/platform-admin.md.
+ * Belongs to `kici-admin`: it works on the orchestrator's database.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

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

@@ -18,8 +18,8 @@
  *
  *   Direct-DB mode: activated when `--database-url` is passed (or
  *   KICI_DATABASE_URL / DATABASE_URL is set). Opens its own pool and runs the
- *   SQL directly via *Direct helpers in @kici-dev/shared. Used by E2E
- *   `globalSetup` helpers that need to seed envs before the orchestrator is up.
+ *   SQL directly via *Direct helpers in @kici-dev/shared, so a setup script can
+ *   seed contexts before the orchestrator is up.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

package/dist/cli/commands/event-dlq.d.ts

@@ -6,12 +6,11 @@
  *   event-dlq retry <id>     — clear DLQ flag, schedule for retry, pg_notify
  *   event-dlq discard <id>   — permanently delete a DLQ event
  *
- * Operator dogfooding path for at-least-once event delivery. Customers
- * should generally never see anything in
- * the DLQ — when something lands here it usually means a workflow handler is
- * consistently failing and should be fixed at its root cause. This CLI is the
- * triage surface: inspect last_error, retry once a fix is deployed, or discard
- * if the event is no longer relevant.
+ * Operator triage path for at-least-once event delivery. Customers should
+ * generally never see anything in the DLQ — when something lands here it
+ * usually means a workflow handler is consistently failing and should be fixed
+ * at its root cause. This CLI is the triage surface: inspect last_error, retry
+ * once a fix is deployed, or discard if the event is no longer relevant.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

package/dist/cli/commands/event-log.d.ts

@@ -2,9 +2,8 @@
  * Inbound webhook delivery log commands for kici-admin.
  *
  * Operator-facing read access to the orchestrator's event_log table via the
- * admin HTTP API. Dogfood replacement for raw psql / log-grep when an
- * operator asks "did delivery <id> arrive, and what did its payload look
- * like".
+ * admin HTTP API. Use it instead of raw psql / log-grep when an operator
+ * asks "did delivery <id> arrive, and what did its payload look like".
  *
  *   event-log list   List inbound deliveries with filters
  *   event-log show   Show a single delivery (optionally with payload)

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

@@ -7,9 +7,7 @@
  * READ-ONLY — mutations (purge-stale) live in `maintenance.ts` instead.
  * Dual-mode: HTTP (via AdminApiClient) or `--database-url` (direct DB).
  *
- * supersedes the original `cache list|show` framing: the real tables
- * the E2E call sites touch are execution_runs / execution_jobs, not
- * dedup_cache.
+ * The rows come from execution_runs / execution_jobs, not dedup_cache.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

package/dist/cli/commands/local-hook.d.ts

@@ -1,7 +1,8 @@
 /**
  * Render the post-receive hook script. For each pushed ref the hook calls
- * `kici-admin source trigger-local <id> --ref <ref> --sha <new> --base-url <url>`,
- * so a push to any branch dispatches a run for that ref.
+ * `kici-admin source trigger-local <id> --ref <ref> --before <old> --sha <new> --base-url <url>`,
+ * so a push to any branch dispatches a run for that ref, and its changed files
+ * are the commits the push added (`<old>..<new>`).
  */
 export declare function renderPostReceiveHook(opts: {
     sourceId: string;

package/dist/cli/commands/local-trigger.d.ts

@@ -5,6 +5,11 @@ export interface LocalTriggerInput {
     event: 'push' | 'pull_request';
     ref: string;
     sha: string;
+    /**
+     * The commit before the push. With it the changed files are `before..sha`;
+     * without it the push has no range and path filters match conservatively.
+     */
+    before?: string;
     defaultBranch: string;
 }
 export interface LocalTriggerRequest {
@@ -19,6 +24,8 @@ export declare function readRepoHead(repoPath: string): {
     ref: string;
     sha: string;
 };
+/** The parent of `sha` in a local repo, or undefined for a root commit or an unreadable repo. */
+export declare function readParentSha(repoPath: string, sha: string): string | undefined;
 /** POST the trigger request to the orchestrator base URL. Returns the HTTP status. */
 export declare function sendLocalTrigger(baseUrl: string, req: LocalTriggerRequest): Promise<number>;
 //# sourceMappingURL=local-trigger.d.ts.map