@kici-dev/orchestrator 0.6.1 → 0.8.0

package/dist/scaler/types.d.ts

@@ -97,16 +97,24 @@ export interface SpawnContext {
      * single source, and computing them twice is the defect this field closes.
      */
     platformTaints?: readonly string[];
+    /**
+     * The full taint gate the spawned agent is registered under: the pool's
+     * configured `mandatoryLabels` plus every derived platform taint, resolved
+     * by `ScalerManager` for the label set this spawn belongs to — the same set
+     * the durable spawn row carries. A backend publishes it (an event scaler puts
+     * it on the scale-up payload) so a provisioning workflow sees the gate the
+     * agent will actually be held to. A backend must never derive it itself: the
+     * manager is the single source, exactly as for `platformTaints`.
+     */
+    mandatoryLabels?: readonly string[];
 }
 /**
- * Network policy controlling RFC1918 and internet access for agents in this label set.
+ * Network policy controlling RFC1918 and internet access for agents in this
+ * label set. Defined in `@kici-dev/shared/net` alongside the nftables rule builder
+ * that consumes it, and re-exported here so scaler call sites are unchanged.
  */
-export interface NetworkPolicy {
-    /** CIDR ranges allowed as exceptions to the default RFC1918 block */
-    allowlist?: string[];
-    /** Block all outbound traffic except allowlisted ranges */
-    denyAll?: boolean;
-}
+import type { NetworkPolicy } from '@kici-dev/shared/net';
+export type { NetworkPolicy };
 /**
  * Image pull policy for container-backend agent images.
  *

package/dist/scaler/warm-pool.d.ts

@@ -125,10 +125,12 @@ export declare class WarmPoolManager {
      * Start the periodic tick: reap surplus agents past their idle timeout, then
      * top the pools back up.
      *
-     * The first pass runs immediately rather than a tick later. Both hosts call
-     * this only after `ensureHostsReady()`, so spawning here is safe — and
-     * waiting would leave the pool empty for 30 seconds after every restart,
-     * which is precisely the cold start it exists to remove.
+     * The first pass runs immediately rather than a tick later. The one caller
+     * is `ScalerManager.startWarmPools()`, which each host reaches only after
+     * `ensureHostsReady()` and — on the coordinator — after the event emitter
+     * is assigned, so spawning here is safe. Waiting a tick instead would leave
+     * the pool empty for 30 seconds after every restart, which is precisely the
+     * cold start it exists to remove.
      */
     start(): void;
     /**

package/dist/secrets/config.d.ts

@@ -24,6 +24,18 @@ export interface SecretStoreConfig {
  * @throws If neither env var nor key file provides a valid key.
  */
 export declare function loadMasterKey(envKey?: string, keyFilePath?: string): Buffer;
+/**
+ * Load the master key MATERIAL — the raw configured string, before
+ * {@link deriveKey}. Same env-then-file precedence as {@link loadMasterKey}.
+ *
+ * Several master-key-wrapped stores take the key as a string and derive it
+ * themselves (`unwrapPrivateJwk`, `ephemeral-keys.decryptPrivateKey`). Reading
+ * `config.secretKey` at those call sites honours `KICI_SECRET_KEY` but silently
+ * ignores `KICI_SECRET_KEY_FILE`, so an operator who supplies the key by file
+ * gets no signing key and no dashboard-encryption key. Resolving the material
+ * here keeps one precedence rule for both the Buffer and string forms.
+ */
+export declare function loadMasterKeyMaterial(envKey?: string, keyFilePath?: string): string;
 /**
  * Load the old (previous) master encryption key for key rotation.
  *
@@ -35,6 +47,42 @@ export declare function loadMasterKey(envKey?: string, keyFilePath?: string): Bu
  * @returns 32-byte Buffer or undefined if no old key is configured.
  */
 export declare function loadOldMasterKey(envKey?: string, keyFilePath?: string): Buffer | undefined;
+/**
+ * Load the old master key MATERIAL — the raw configured string, before
+ * {@link deriveKey}. The string-form counterpart of {@link loadOldMasterKey},
+ * for the wrapped stores that take the key as a string.
+ */
+export declare function loadOldMasterKeyMaterial(envKey?: string, keyFilePath?: string): string | undefined;
+/**
+ * The master key in both the forms the wrapped stores need: the raw configured
+ * material (for stores that take a string and derive it themselves) and the
+ * derived AES key (for stores that hold a Buffer), each paired with the
+ * previous generation during a rotation grace window.
+ *
+ * Resolved once at boot so every master-key-wrapped store agrees on the same
+ * key, and so `KICI_SECRET_KEY_FILE` reaches all of them rather than only the
+ * two that happened to call {@link loadMasterKey}.
+ */
+export interface ResolvedMasterKeys {
+    /** Raw configured key material, before {@link deriveKey}. */
+    material: string;
+    /** The previous generation's raw material, when a rotation window is open. */
+    materialOld: string | undefined;
+    /** Derived 32-byte AES key. */
+    current: Buffer;
+    /** The previous generation's derived key, when a rotation window is open. */
+    old: Buffer | undefined;
+}
+/**
+ * Resolve the master key (and, when configured, its predecessor) from the
+ * env-then-file precedence both loaders use. Returns null when no master key is
+ * configured at all — the secrets subsystem is off in that case.
+ */
+export declare function resolveMasterKeys(opts: {
+    secretKey?: string | undefined;
+    secretKeyFile?: string | undefined;
+    secretKeyFileOld?: string | undefined;
+}): ResolvedMasterKeys | null;
 /**
  * Load the full secret store configuration.
  *

package/dist/secrets/dashboard-encryption-key.d.ts

@@ -19,10 +19,29 @@ export interface ReconcileDashboardEncryptionKeyDeps {
     isLeader: () => boolean;
     /** The orchestrator master key (`KICI_SECRET_KEY`), for db-custody wrapping. */
     secretKey: string | undefined;
+    /**
+     * The previous master key (`KICI_SECRET_KEY_OLD`), during a rotation grace
+     * window. Lets a row still sealed under the old key unwrap, and drives the
+     * boot self-heal that re-seals it under the current key.
+     */
+    oldSecretKey?: string | undefined;
     /** Called once when a NEW kid is first activated (audit log, system actor). */
     audit: (info: {
         kid: string;
     }) => Promise<void> | void;
+    /**
+     * Re-seal the active row when it opened only under the OLD master key, back
+     * under the current one. Optional: when unset the key still resolves but
+     * stays stranded. Best-effort — a failure is warned and never blocks the
+     * boot. The recovery path for a deployment stranded by a rotation that ran
+     * before `dashboard_encryption_keys` was part of the sweep.
+     */
+    selfHeal?: (row: {
+        kid: string;
+        key_version: number;
+    }, privateKeyDer: Buffer) => Promise<void>;
+    /** Structured warn sink for the self-heal notice. */
+    logWarn?: (message: string, meta: Record<string, unknown>) => void;
 }
 /** The resolved active dashboard-encryption key + a per-request decrypt closure. */
 export interface ResolvedDashboardEncryptionKey {

package/dist/secrets/ephemeral-keys.d.ts

@@ -1,3 +1,6 @@
+/** AAD string used when encrypting/decrypting private keys with secret key. */
+/** AAD binding a wrapped run private key to its purpose (AES-GCM authenticated data). */
+export declare const PRIVATE_KEY_AAD = "ephemeral-private-key";
 /**
  * Generate an X25519 key pair for a run.
  *
@@ -16,14 +19,17 @@ export declare function generateRunKeyPair(): {
  */
 export declare function encryptPrivateKey(privateKey: Buffer, secretKey: string): string;
 /**
- * Decrypt a run's private key using the orchestrator secret key (KICI_SECRET_KEY).
+ * Decrypt a run's private key using the orchestrator secret key
+ * (KICI_SECRET_KEY), falling back to the old key during a rotation grace
+ * window. Same dual-key pattern as `PgSecretStore.decryptWithFallback`.
  *
  * @param encryptedData - Base64-encoded encrypted private key
  * @param secretKey - Orchestrator secret key (hex or base64 string)
+ * @param oldSecretKey - Previous master key, during a rotation grace window
  * @returns DER-encoded private key Buffer
- * @throws If decryption fails
+ * @throws If decryption fails under both keys
  */
-export declare function decryptPrivateKey(encryptedData: string, secretKey: string): Buffer;
+export declare function decryptPrivateKey(encryptedData: string, secretKey: string, oldSecretKey?: string): Buffer;
 /**
  * Decrypt a secret output envelope produced by an agent.
  *

package/dist/secrets/index.d.ts

@@ -6,7 +6,9 @@
  */
 export { PgSecretStore } from './pg-secret-store.js';
 export { AuditLogger } from './audit-logger.js';
-export { loadMasterKey, loadOldMasterKey, loadSecretStoreConfig, type SecretStoreConfig, } from './config.js';
+export { loadMasterKey, loadMasterKeyMaterial, loadOldMasterKey, loadOldMasterKeyMaterial, loadSecretStoreConfig, resolveMasterKeys, type ResolvedMasterKeys, type SecretStoreConfig, } from './config.js';
+export { secretOutputAad, sealSecretOutput, unsealSecretOutput } from './secret-output-crypto.js';
+export { rotateMasterKeyWrappedTables, selfHealStrandedDashboardKey, selfHealStrandedSigningKey, strandedKeyError, type MasterKeyRotationResult, type SweepResult, } from './master-key-rotation.js';
 export { encrypt, decrypt, deriveKey, generateMasterKey, type EncryptedValue, } from '@kici-dev/shared';
 export { VaultSecretStore, type VaultConfig } from './vault-secret-store.js';
 export { SecretResolver, type SecretResolverDeps, type ResolvedSecretMeta, type ContextStoreLike, type BindingStoreLike, type SecretStoreLike, } from './secret-resolver.js';

package/dist/secrets/job-secret-gate.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The one resolution path for a job-originated qualified secret reference.
+ *
+ * A workflow may name a secret as `<context>:<key>` in a git credential or a
+ * container-registry auth reference. Those references are resolved
+ * orchestrator-side, outside the job's bound `contexts:` list — which is what
+ * the published examples in `docs/user/patterns/git-credentials.md` and
+ * `docs/user/container-jobs.md` do, so a bound-only rule would refuse every
+ * documented use.
+ *
+ * Resolving outside the bindings is not the same as resolving with no
+ * authorization. Three independent checks stand between a job and the value,
+ * and this module is where all three run:
+ *
+ *   1. the reserved namespace is refused — a job may never name the
+ *      orchestrator's own `__system__` org or a `__…__` scope;
+ *   2. an untrusted contributor gets nothing, mirroring the install-secrets
+ *      strip;
+ *   3. the NAMED context's own protection rules run against this dispatch —
+ *      the branch restriction, `minimumTrust`, concurrency, reviewers and wait
+ *      timers the operator configured on `prod` apply to a `prod:` reference.
+ *
+ * The lock declaration is the fourth check and lives at the callers: the relay
+ * pins the wire ref to `execution_jobs.git_credentials`, and container-registry
+ * refs come from the lock by construction.
+ *
+ * Callers use this instead of `SecretResolverApi.resolveNamedInternal`, which
+ * is the system-scoped direct lookup and applies none of the above.
+ */
+import type { TrustTier } from '@kici-dev/engine';
+import type { ContextStore } from '../contexts/context-store.js';
+import { type JobDispatchContext } from '../contexts/protection/pipeline.js';
+import type { SecretResolverApi } from './secret-resolver.js';
+/**
+ * The org id the orchestrator stores its OWN credentials under — GitHub App
+ * private keys, webhook signing secrets, universal-git PATs. A job's `orgId` is
+ * its `customer_id`, so a job can never legitimately present this value.
+ */
+export declare const RESERVED_ORG_ID = "__system__";
+/**
+ * Refuse a reference into the orchestrator's own reserved namespace.
+ *
+ * Today no job can reach one anyway — a job's `orgId` is its `customer_id`, so
+ * `(orgId, '__source__/x')` misses. That is a consequence of two unrelated
+ * constants agreeing, not a check: an org literally named `__system__`, a
+ * source-scoped secret copied into a customer org, or a helper resolving under
+ * a caller-supplied org would each remove it silently. Stating it makes it
+ * survive those changes.
+ *
+ * The message names the reserved namespace, never the secret: a job that
+ * guessed a scope learns only that the scope is reserved.
+ */
+export declare function assertResolvableJobScope(orgId: string, context: string): void;
+export interface ResolveJobQualifiedSecretArgs {
+    resolver: SecretResolverApi;
+    contextStore: ContextStore;
+    orgId: string;
+    runId?: string;
+    jobId?: string;
+    /** The context half of the workflow's `<context>:<key>` reference. */
+    context: string;
+    /** The secret-name half. Never logged, never quoted back in an error. */
+    key: string;
+    /** The dispatch facts the protection rules evaluate against, from server truth. */
+    dispatchCtx: JobDispatchContext;
+    trustTier: TrustTier | undefined;
+}
+/**
+ * Resolve one `<context>:<key>` reference on behalf of a running job.
+ *
+ * Throws — with a reason naming the check that refused — rather than returning
+ * null, because every caller treats a miss as a hard failure and a nullable
+ * return is one `??` away from becoming a silent fallback.
+ */
+export declare function resolveJobQualifiedSecret(args: ResolveJobQualifiedSecretArgs): Promise<string>;
+//# sourceMappingURL=job-secret-gate.d.ts.map

package/dist/secrets/master-key-rotation.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Master-key rotation sweeps for the four wrapped stores `rotate-key` did not
+ * cover: the provenance signing key, the dashboard-encryption key, run
+ * ephemeral keys, and stored secret outputs.
+ *
+ * Each sweep runs in its own transaction with the same skip-and-count
+ * discipline as `BackendRegistry.rotateKey` — a row neither key opens is
+ * counted and left alone rather than failing the whole rotation, so the
+ * operator sees a non-zero `skipped` and can act on it. Each sweep is
+ * idempotent: re-running over rows already at the current key re-seals them at
+ * the next version, which is exactly what the no-old-key "periodic
+ * re-encryption" mode is for.
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import { wrapPrivateJwk } from '../oidc/db-signer.js';
+import type { ResolvedMasterKeys } from './config.js';
+/** One store's rotation outcome. Mirrors the three existing sweeps' shape. */
+export interface SweepResult {
+    reEncrypted: number;
+    skipped: number;
+}
+/** Every wrapped store this module sweeps, keyed as the API reports them. */
+export interface MasterKeyRotationResult {
+    signingKeys: SweepResult;
+    dashboardKeys: SweepResult;
+    ephemeralKeys: SweepResult;
+    secretOutputs: SweepResult;
+}
+type Warn = (message: string, meta: Record<string, unknown>) => void;
+/**
+ * Run all four sweeps, each in its own transaction so a bug in one cannot roll
+ * back a good rotation of another. Order is least-to-most volume, so the
+ * singleton key tables — the two whose loss brings the orchestrator down — move
+ * first.
+ */
+export declare function rotateMasterKeyWrappedTables(db: Kysely<Database>, keys: ResolvedMasterKeys, warn: Warn): Promise<MasterKeyRotationResult>;
+/**
+ * Re-seal a single row that decrypted only under the OLD master key, back under
+ * the current one. This is the boot self-heal: a deployment already stranded by
+ * a rotation that ran before these tables were swept recovers by restoring the
+ * old key once and restarting.
+ *
+ * The `key_version` match is the concurrent-rotation guard — mirrors
+ * `BackendRegistry.selfHealStrandedRow`. A rotation running at the same time
+ * has already moved the version, so this UPDATE matches no row and is a no-op
+ * rather than a clobber.
+ */
+export declare function selfHealStrandedSigningKey(db: Kysely<Database>, row: {
+    kid: string;
+    key_version: number;
+}, privateJwk: Parameters<typeof wrapPrivateJwk>[0], keys: ResolvedMasterKeys): Promise<void>;
+/** The dashboard-encryption twin of {@link selfHealStrandedSigningKey}. */
+export declare function selfHealStrandedDashboardKey(db: Kysely<Database>, row: {
+    kid: string;
+    key_version: number;
+}, privateKeyDer: Buffer, keys: ResolvedMasterKeys): Promise<void>;
+/**
+ * Loud, recovery-pointing error for a key stranded by a master-key rotation.
+ * Same shape and intent as `BackendRegistry.strandedError`: the operator needs
+ * to be told the recovery path, not just that AES-GCM failed.
+ */
+export declare function strandedKeyError(store: string): Error;
+export {};
+//# sourceMappingURL=master-key-rotation.d.ts.map

package/dist/secrets/secret-output-crypto.d.ts

@@ -0,0 +1,17 @@
+/** AAD binding a stored secret output to its run (AES-GCM authenticated data). */
+export declare function secretOutputAad(runId: string): string;
+/** Seal a secret-output plaintext under the master key at `keyVersion`. */
+export declare function sealSecretOutput(plaintext: string, masterKey: Buffer, runId: string, keyVersion?: number): {
+    data: string;
+    keyVersion: number;
+};
+/**
+ * Unseal a stored secret output with the current master key, falling back to
+ * the old key during a rotation grace window. Same dual-key pattern as
+ * `PgSecretStore.decryptWithFallback`. Throws when neither key opens it.
+ */
+export declare function unsealSecretOutput(encryptedValue: string, runId: string, keys: {
+    current: Buffer;
+    old?: Buffer;
+}, keyVersion?: number): string;
+//# sourceMappingURL=secret-output-crypto.d.ts.map

package/dist/secrets/secret-resolver.d.ts

@@ -38,7 +38,7 @@ export interface BindingStoreLike {
  * Minimal secret store interface (subset needed by resolver).
  * getAllSecrets returns raw encrypted secrets; decrypt decrypts a single secret.
  * getSecrets returns a decrypted key-value map for a single scope (used by
- * resolveNamed for source-scoped credential lookup).
+ * resolveNamedInternal for source-scoped credential lookup).
  */
 export interface SecretStoreLike {
     getAllSecrets(orgId: string): Promise<ScopedSecret[]>;
@@ -70,7 +70,12 @@ export interface ResolvedSecretMeta {
  */
 export interface SecretResolverApi {
     resolveForJob(orgId: string, contextName: string, hostCtx?: HostFacts): Promise<Record<string, string>>;
-    resolveNamed(orgId: string, scope: string, key: string, opts?: {
+    /**
+     * System-scoped direct lookup — no context binding, no protection rule, no
+     * trust tier. A job-originated reference goes through
+     * `resolveJobQualifiedSecret` instead. See the implementation's doc comment.
+     */
+    resolveNamedInternal(orgId: string, scope: string, key: string, opts?: {
         store?: string;
         runId?: string;
         jobId?: string;
@@ -107,9 +112,21 @@ export declare class SecretResolver implements SecretResolverApi {
     resolveForJob(orgId: string, contextName: string, hostCtx?: HostFacts): Promise<Record<string, string>>;
     /**
      * Resolve a single named secret by (orgId, scope, key), optionally scoped to
-     * a specific backend. Bypasses context bindings — this is a direct
-     * lookup used for source-scoped credentials (e.g. universal-git PAT/SSH
-     * keys stored under `__source__/<sourceId>`).
+     * a specific backend.
+     *
+     * SYSTEM-SCOPED CALLERS ONLY. It applies no authorization of any kind: no
+     * context binding, no protection rule, no trust tier. Its legitimate callers
+     * resolve the orchestrator's OWN credentials, under scopes a workflow can
+     * never name — `resolveSourceCredential` (`__source__/<sourceId>`) and the
+     * bringup API's host secret refs.
+     *
+     * A JOB-ORIGINATED reference goes through `resolveJobQualifiedSecret`
+     * (`secrets/job-secret-gate.ts`) instead, which runs the named context's
+     * protection rules and the trust-tier strip before reaching this method. The
+     * `Internal` suffix is the enforcement: this method's doc comment already
+     * warned that it bypassed context bindings, and three call sites took it
+     * anyway — a warning is not a boundary, but a name shows up in a grep of
+     * callers.
      *
      * When `store` is omitted, backends are tried in Map iteration order (the
      * order they were registered) and the first hit wins. An explicit `store`
@@ -120,7 +137,7 @@ export declare class SecretResolver implements SecretResolverApi {
      * fail-fast policy — the caller asked for a specific backend and
      * it's gone.
      */
-    resolveNamed(orgId: string, scope: string, key: string, opts?: {
+    resolveNamedInternal(orgId: string, scope: string, key: string, opts?: {
         store?: string;
         runId?: string;
         jobId?: string;

package/dist/secrets/source-credentials.d.ts

@@ -9,7 +9,7 @@
  * the key name.
  *
  * This module is a thin, opinionated wrapper around
- * `SecretResolver.resolveNamed()` that:
+ * `SecretResolver.resolveNamedInternal()` that:
  *   1. Builds the canonical scope string for a given source ID.
  *   2. Delegates to the resolver's direct-lookup method.
  *   3. Returns a structured failure (null + reason) so callers can emit

package/dist/secrets/token-manager.d.ts

@@ -18,9 +18,12 @@ export declare class TokenManager {
      * @param routingKey - Optional routing key scope (null = all).
      * @param expiresAt - Optional absolute expiry. When omitted the token
      *   never expires (null); `validate()` already enforces the column.
+     * @param subject - Optional intended holder (an OIDC `sub` or an email).
+     *   Advisory only — never read when authorizing. Omitted leaves the token
+     *   `unlinked` in the RBAC drift report.
      * @returns The plaintext token (shown once) and the row ID.
      */
-    generateToken(label: string, role: Role, routingKey?: string | null, expiresAt?: Date | null): Promise<{
+    generateToken(label: string, role: Role, routingKey?: string | null, expiresAt?: Date | null, subject?: string | null): Promise<{
         token: string;
         id: string;
     }>;

package/dist/security/identity-link.d.ts

@@ -40,7 +40,7 @@ export interface IdentityLink {
  * the answer is unambiguous; when they disagree there is no way to tell here
  * which provider serves the commit, so this answers undefined rather than
  * naming the wrong account. Undefined is a safe answer at every call site: the
- * attribution is simply omitted, never replaced by the raw subject id.
+ * attribution is omitted, never replaced by the raw subject id.
  */
 export declare function resolveLinkedUsername(identityLinks: IdentityLink[], userId: string): string | undefined;
 /**

package/dist/security/reduced-privilege-note.d.ts

@@ -43,6 +43,11 @@ export declare const REDUCED_PRIVILEGE_MARKER = "**Reduced privileges (untrusted
  * - `resolveInstallSecrets` returns `npmRegistries: undefined` and
  *   `installEnvSecrets: undefined` for a resolved non-trusted tier, so the run
  *   carries neither.
+ * - the per-job container-registry resolution in `dispatch-matched-workflow.ts`
+ *   is skipped for the same tiers, so `jobConfig` carries no
+ *   `containerRegistryAuth` and a private base image fails to pull. Keyed on
+ *   the tier through the same `isUntrustedTier`, so the clause and the strip
+ *   cannot disagree.
  * - `deriveCacheRefScope` returns the isolated scope for the same tiers, and
  *   `UserCache` confines WRITES to it; a restore still falls back to the shared
  *   scope, so the clause is about what the run saves, not what it can read.

package/dist/security/trust-directory-store.d.ts

@@ -64,7 +64,7 @@ import type { Database } from '../db/types.js';
  * What it does not pin: the field *set*. A fourth directory field added to
  * `trustPolicyUpdateSchema` is not picked up here, and `server.ts` hand-builds
  * the value it passes to `upsertFromPlatform`, so nothing would fail — the new
- * field would simply go unpersisted. Adding one means extending this object and
+ * field would go unpersisted. Adding one means extending this object and
  * that literal together.
  */
 export declare const trustDirectorySchema: z.ZodObject<{

package/dist/security/trust-policy-gate.d.ts

@@ -104,11 +104,12 @@ export declare const DEFAULT_FORK_POLICY: ForkPolicy;
  * events is the fail-closed posture: nothing foreign dispatches, and the event
  * is dropped rather than parked in a queue nobody is watching.
  *
- * This is NOT necessarily a brief transient. The Platform sends
- * `trust_policy.update` only when the org has a `trust_policies` row, and that
- * row is created lazily on a dashboard read — so an org that has never opened
- * Settings > CI trust receives no push at all and stays on these values
- * indefinitely.
+ * This is NOT necessarily a brief transient. The Platform pushes
+ * `trust_policy.update` on every authenticated handshake, and for an org with
+ * no `trust_policies` row it pushes its own defaults, whose fork switch is
+ * `ignore` as well. So an org that has never opened Settings > CI trust holds
+ * these values for as long as nobody chooses otherwise, and every fork pull
+ * request it receives is dropped.
  */
 export declare const FAIL_CLOSED_POLICY: TrustPolicy;
 /**
@@ -127,17 +128,80 @@ export declare const FAIL_CLOSED_POLICY: TrustPolicy;
  * can approve it — which an ignored event is not.
  */
 export declare const READ_FAILURE_POLICY: TrustPolicy;
+/**
+ * Where the policy in force came from.
+ *
+ * The three arms are three different things to tell an operator, and the
+ * difference is what makes a verdict explicable: `stored` is a choice somebody
+ * made, `unconfigured` is what nobody choosing looks like, and `read-failure`
+ * is neither — it is the orchestrator declining to guess.
+ *
+ * Named for the resolution rather than the policy, because
+ * `TrustPolicySource` is already taken by a sibling in this directory —
+ * `trust-policy-store.ts` answers "who WROTE the cached row" (`platform` /
+ * `local`) and exports that name from the package barrel. Two exported types
+ * of that name would read as one to anyone grepping for it.
+ */
+export declare const EffectivePolicySource: z.ZodEnum<{
+    "read-failure": "read-failure";
+    stored: "stored";
+    unconfigured: "unconfigured";
+}>;
+export type EffectivePolicySource = z.infer<typeof EffectivePolicySource>;
+/** A policy plus where it came from. */
+export interface EffectiveTrustPolicy {
+    policy: TrustPolicy;
+    source: EffectivePolicySource;
+}
 /**
  * Pick the policy to evaluate. A stored row always wins; without one every
  * orchestrator gets the fail-closed policy above.
  *
+ * Returns the source alongside the policy because the values alone cannot
+ * answer "why was my pull request dropped?" — `ignore` reads identically
+ * whether an operator chose it or nobody chose anything.
+ *
+ * `read-failure` is not produced here: this function is handed the outcome of a
+ * read, not the read itself, so a caller whose read THREW builds that arm from
+ * `READ_FAILURE_POLICY` at its own call site.
+ *
  * `mode` no longer selects between two postures — an independent orchestrator
  * has no upstream authority, which is a reason to be stricter rather than more
  * permissive — but it stays on the signature so callers that legitimately hold
  * a mode do not have to change, and so a future per-mode difference has a place
  * to land.
  */
-export declare function resolveEffectivePolicy(stored: StoredTrustPolicy | null, _mode: OrchestratorMode): TrustPolicy;
+export declare function resolveEffectivePolicy(stored: StoredTrustPolicy | null, _mode: OrchestratorMode): EffectiveTrustPolicy;
+/**
+ * The org fork switch in force for one delivery, and where it came from.
+ *
+ * Carried out of the evaluation so a call site that has to EXPLAIN the verdict
+ * — the drop site, which is the one exit that leaves nothing else behind — can
+ * name both without re-reading the store.
+ */
+export interface ForkSwitchContext {
+    policy: ForkPolicy;
+    source: EffectivePolicySource;
+    /**
+     * True where a Platform owns this org's policy. It decides which remedy the
+     * explanation names: an independent orchestrator has no dashboard to send its
+     * operator to, and a Platform-attached one answers a local write with a 409.
+     */
+    platformManaged: boolean;
+}
+/**
+ * The sentence written on the event-log row of a dropped fork pull request.
+ *
+ * This row is the ONLY trace an `ignore` verdict leaves: there is no run, no
+ * check status, and nothing on the pull request itself. So it names the switch
+ * value, where that value came from, and what did not happen — an operator
+ * reading it must not have to already know the fork switch exists.
+ *
+ * When nobody chose the switch it also names the remedy, which follows the
+ * deployment: the dashboard owns the policy wherever a Platform is attached,
+ * and `kici-admin trust-policy set` owns it where none is.
+ */
+export declare function forkDropExplanation(forkSwitch: ForkSwitchContext): string;
 /**
  * Evaluate the fork switch.
  *

package/dist/security/trust-tier.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The one predicate for "this run's contributor is not trusted".
+ *
+ * It lives beside `trust-resolver.ts` and `reduced-privilege-note.ts` — the
+ * modules that decide and render the posture it reads — rather than inside any
+ * one consumer, because three unrelated subsystems now withhold credentials on
+ * it: the install-secrets resolver, the job secret gate, and container-registry
+ * auth. A copy per consumer is how two of them would end up disagreeing about
+ * what an absent tier means.
+ */
+import type { TrustTier } from '@kici-dev/engine';
+/**
+ * True when the resolved trust tier is anything other than 'trusted'.
+ *
+ * `undefined` is the LENIENT direction here: an unresolved tier leaves
+ * credentials in place, while `deriveCacheRefScope` maps the same `undefined`
+ * to the isolated cache scope, which is what `resolveWorkflowDockerfileBuilds`
+ * then denies unless the org opted in. `evaluateTrustGate` reads it leniently
+ * too; `deriveCacheRefScope`, `selectLockFileSource`, and the trust-policy
+ * gate's `isNonTrusted` all read the same `undefined` strictly.
+ *
+ * Several dispatch paths reach it with no tier, and the set is open — a
+ * provider bundle carrying a fork model does not keep a run out of it. Among
+ * them: an internally-triggered run whose inheritance lookup degrades, a
+ * pull-request event from a provider with no fork model, a cross-source
+ * dispatch, and a `kici run` remote test run. Treat "no tier" as its own case
+ * rather than as a proxy for any one of them. Documented for operators in
+ * `docs/user/events.md` under the trust-tier rules.
+ */
+export declare function isUntrustedTier(tier: TrustTier | undefined): boolean;
+//# sourceMappingURL=trust-tier.d.ts.map

package/dist/server.d.ts

@@ -13,7 +13,7 @@
  * Graceful shutdown in reverse order:
  * Platform client -> agent WS -> heartbeat -> HTTP -> DB
  */
-import type { OrchestratorFaultInjection } from './testing/fault-injection.js';
+import type { OrchestratorFaultInjection } from './fault-injection-types.js';
 /**
  * Boot the Platform-connected orchestrator. Factored out of the module entry so
  * both this file's production entry (which passes no fault injection) and the