@opengeni/worker-bundle 1.0.0-canary.0 → 1.0.0

package/src/activities/workspace-credential-provider.ts

@@ -0,0 +1,283 @@
+import { environmentsEncryptionKeyBytes, type Settings } from "@opengeni/config";
+import {
+  CredentialProviderResponse,
+  OPENGENI_SIGNATURE_HEADER,
+  signOpenGeniPayload,
+  type CredentialProviderRequest,
+  type RunCredentialsRequest,
+  type RunCredentialsResolution,
+} from "@opengeni/contracts";
+import {
+  decryptEnvironmentValue,
+  resolveWorkspaceCredentialProvider,
+  resolveInitiatingHuman,
+  type Database,
+} from "@opengeni/db";
+import { pinnedFetch, type OutboundNetworkSettings } from "@opengeni/network";
+
+const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+export const GIT_CREDENTIALS_FILE = "git/credentials";
+export const GIT_CREDENTIALS_FILE_ENV = "OPENGENI_GIT_CREDENTIALS_FILE";
+
+export class CredentialProviderError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CredentialProviderError";
+  }
+}
+
+export type WorkspaceRunCredentialResolver = (
+  input: RunCredentialsRequest,
+) => Promise<RunCredentialsResolution>;
+
+type ProviderOk = Extract<CredentialProviderResponse, { status: "ok" }>;
+
+function gitCredentialLine(entry: NonNullable<ProviderOk["git"]>[number]): string {
+  const username = encodeURIComponent(entry.username ?? "x-access-token");
+  return `https://${username}:${encodeURIComponent(entry.password)}@${entry.host.toLowerCase()}`;
+}
+
+/**
+ * Turn the provider's `git` sugar into ordinary run-credential material: one
+ * renewable credential-store file plus a read-only helper configured through
+ * GIT_CONFIG_* environment entries appended after any the host already set.
+ */
+export function withGitCredentialHelper(response: ProviderOk): ProviderOk {
+  if (!response.git?.length) return response;
+  const environment = { ...response.environment };
+  const existingCount = Number.parseInt(environment.GIT_CONFIG_COUNT ?? "0", 10);
+  const index = Number.isFinite(existingCount) && existingCount > 0 ? existingCount : 0;
+  environment[`GIT_CONFIG_KEY_${index}`] = "credential.helper";
+  environment[`GIT_CONFIG_VALUE_${index}`] =
+    `!f() { test "$1" = get && sed '/^path=/d' | git credential-store --file="$${GIT_CREDENTIALS_FILE_ENV}" get; }; f`;
+  environment.GIT_CONFIG_COUNT = String(index + 1);
+  return {
+    ...response,
+    environment,
+    files: [
+      ...(response.files ?? []),
+      {
+        path: GIT_CREDENTIALS_FILE,
+        content: `${response.git.map(gitCredentialLine).join("\n")}\n`,
+        mode: "0400",
+      },
+    ],
+    fileEnvironment: {
+      ...response.fileEnvironment,
+      [GIT_CREDENTIALS_FILE_ENV]: GIT_CREDENTIALS_FILE,
+    },
+  };
+}
+
+export function credentialProviderRequestBody(
+  input: RunCredentialsRequest,
+  initiatingHumanSubjectId: string | null,
+  initiatingHuman: CredentialProviderRequest["initiatingHuman"] = null,
+  selection: Pick<CredentialProviderRequest, "lane" | "mcpServers"> = {
+    lane: "workspace",
+    mcpServers: [],
+  },
+): CredentialProviderRequest {
+  const via = input.initiatorContext.via;
+  const latestHop = Array.isArray(via) ? via.at(-1) : null;
+  return {
+    type: "credentials.request",
+    lane: selection.lane,
+    mcpServers: selection.mcpServers.map(({ id, url }) => ({ id, url })),
+    purpose: input.purpose,
+    forceRefresh: input.forceRefresh,
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    sessionId: input.sessionId,
+    rootSessionId: input.rootSessionId,
+    parentSessionId: input.parentSessionId,
+    turnId: input.turnId,
+    attemptId: input.attemptId,
+    initiator: { kind: input.initiator.kind, subjectId: input.initiator.subjectId },
+    initiatorContext: {
+      kind:
+        latestHop?.kind === "agent"
+          ? "agent"
+          : input.initiator.kind === "subject"
+            ? "human"
+            : "service",
+      initiator: input.initiator,
+      context: input.initiatorContext,
+    },
+    initiatingHumanSubjectId,
+    initiatingHuman,
+    sandboxBackend: input.effectiveSandboxBackend,
+    sandboxOs: input.sandboxOs,
+  };
+}
+
+/** Drop undefined-valued keys; the runtime normalizer re-validates everything. */
+function wire<T>(value: unknown): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+export function toRunCredentialsResolution(
+  response: CredentialProviderResponse,
+  scope: { accountId: string; workspaceId: string; sessionId: string },
+): RunCredentialsResolution {
+  if (response.status === "not_applicable") return { status: "not_applicable", ...scope };
+  if (response.status === "auth_needed") {
+    return wire({ status: "auth_needed", ...scope, authNeeded: response.authNeeded });
+  }
+  const { git: _git, ...material } = withGitCredentialHelper(response);
+  return wire({ ...material, status: "ok", ...scope, environment: material.environment ?? {} });
+}
+
+async function readBoundedText(response: Response): Promise<string> {
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
+    throw new CredentialProviderError("credential provider response is too large");
+  }
+  const reader = response.body?.getReader();
+  if (!reader) return "";
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > MAX_RESPONSE_BYTES) {
+      await reader.cancel().catch(() => undefined);
+      throw new CredentialProviderError("credential provider response is too large");
+    }
+    chunks.push(value);
+  }
+  return new TextDecoder().decode(Buffer.concat(chunks));
+}
+
+export type WorkspaceCredentialProviderDeps = {
+  fetch?: typeof pinnedFetch;
+  resolveProvider?: typeof resolveWorkspaceCredentialProvider;
+  resolveHuman?: typeof resolveInitiatingHuman;
+  /** Trusted selected session-attached remote targets, frozen by the worker. */
+  mcpServers?: readonly { id: string; url: string }[];
+};
+
+/**
+ * Resolve the workspace's configured HTTP credential provider, if any. The
+ * returned resolver has the same contract as a host `runCredentials` port, so
+ * provisioning, file materialization, renewal, and reconnect notices reuse the
+ * existing run-credential lifecycle unchanged.
+ */
+export async function workspaceCredentialProviderResolver(
+  db: Database,
+  settings: Settings,
+  scope: { accountId: string; workspaceId: string },
+  initiatingHumanSubjectId: string | null,
+  deps: WorkspaceCredentialProviderDeps = {},
+): Promise<WorkspaceRunCredentialResolver | null> {
+  const row = await (deps.resolveProvider ?? resolveWorkspaceCredentialProvider)(db, scope);
+  if (!row) return null;
+  if (!row.enabled) {
+    // A disabled workspace override is an explicit pause, not an absent
+    // provider. Return a resolver so the deployment port cannot be borrowed.
+    return async (input) => ({
+      status: "not_applicable",
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      sessionId: input.sessionId,
+    });
+  }
+  const key = environmentsEncryptionKeyBytes(settings);
+  if (!key) {
+    throw new CredentialProviderError(
+      "OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY is required to use a workspace credential provider",
+    );
+  }
+  const fetchImpl = deps.fetch ?? pinnedFetch;
+  const network: OutboundNetworkSettings = settings;
+  const selection = {
+    lane:
+      "workspaceId" in row && row.workspaceId !== null
+        ? ("workspace" as const)
+        : ("organization" as const),
+    mcpServers: (deps.mcpServers ?? []).map(({ id, url }) => ({ id, url })),
+  };
+  return async (input) => {
+    const echo = {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      sessionId: input.sessionId,
+    };
+    // Rotation and disabling take effect on the next outbound request. Never
+    // switch registration mid-attempt if deletion exposes an inherited row.
+    const current = await (deps.resolveProvider ?? resolveWorkspaceCredentialProvider)(db, scope);
+    if (!current?.enabled || current.id !== row.id) {
+      return { status: "not_applicable", ...echo };
+    }
+    const secret = decryptEnvironmentValue(key, current.secretEncrypted);
+    const initiatingHuman = await (deps.resolveHuman ?? resolveInitiatingHuman)(
+      db,
+      scope,
+      initiatingHumanSubjectId,
+      input.turnId,
+    );
+    const body = JSON.stringify(
+      credentialProviderRequestBody(input, initiatingHumanSubjectId, initiatingHuman, selection),
+    );
+    let status: number;
+    let text: string;
+    try {
+      const response = await fetchImpl(
+        current.url,
+        {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            "user-agent": "OpenGeni-CredentialProvider/1",
+            [OPENGENI_SIGNATURE_HEADER]: await signOpenGeniPayload(secret, body),
+          },
+          body,
+          signal: AbortSignal.timeout(current.timeoutMs),
+        },
+        network,
+        { label: "Workspace credential provider", requireHttpsOutsideLocalTest: true },
+      );
+      status = response.status;
+      text = await readBoundedText(response);
+    } catch (error) {
+      return failure(input, echo, `request failed: ${errorName(error)}`);
+    }
+    if (status < 200 || status >= 300) {
+      return failure(input, echo, `returned HTTP ${status}`);
+    }
+    let parsed: CredentialProviderResponse;
+    try {
+      parsed = CredentialProviderResponse.parse(JSON.parse(text));
+    } catch {
+      return failure(input, echo, "returned an invalid response body");
+    }
+    return toRunCredentialsResolution(parsed, echo);
+  };
+}
+
+function errorName(error: unknown): string {
+  if (error instanceof Error) {
+    return error.name === "TimeoutError" || error.name === "AbortError" ? "timeout" : error.name;
+  }
+  return "unknown";
+}
+
+/**
+ * A failed renewal throws so the renewal loop keeps the last good material and
+ * retries with backoff. A failed first provision degrades to a visible
+ * reconnect notice instead of blocking the turn.
+ */
+function failure(
+  input: RunCredentialsRequest,
+  echo: { accountId: string; workspaceId: string; sessionId: string },
+  reason: string,
+): RunCredentialsResolution {
+  const message = `Workspace credential provider ${reason}`;
+  if (input.purpose === "renewal") throw new CredentialProviderError(message);
+  return {
+    status: "auth_needed",
+    ...echo,
+    authNeeded: [{ reason: "refresh_failed", message }],
+  };
+}

package/src/activities-control.ts

@@ -2,10 +2,12 @@ import { createKnowledgeIndexingActivities } from "./activities/knowledge-indexi
 import { createSharedActivityServices } from "./activity-services";
 import { createCodexCapacityActivities } from "./activities/codex-capacity";
 import { createBrowserStateArtifactMaintenanceActivities } from "./activities/browser-state-artifact-reaper";
+import { createBrowserDeadlineCheckpointActivities } from "./activities/browser-deadline-checkpoint";
 import { createAutomationActivities } from "./activities/automations";
 import { createDocumentActivities } from "./activities/documents";
 import { createFileUploadReaperActivities } from "./activities/file-upload-reaper";
 import { createGoalActivities } from "./activities/goals";
+import { createModelCallFactReconcilerActivities } from "./activities/model-call-fact-reconciler";
 import { createKnowledgeSourceSyncActivities } from "./activities/knowledge-source-sync";
 import { createRetainedScreenshotMaintenanceActivities } from "./activities/retained-screenshot-reaper";
 import { createRigVerificationActivities } from "./activities/rig-verification";
@@ -39,7 +41,9 @@ export function createControlActivitiesFromServices(
     ...createCodexCapacityActivities(services),
     ...createRigVerificationActivities(services),
     ...createBrowserStateArtifactMaintenanceActivities(services),
+    ...createBrowserDeadlineCheckpointActivities(services),
     ...createFileUploadReaperActivities(services),
+    ...createModelCallFactReconcilerActivities(services),
     ...createRetainedScreenshotMaintenanceActivities(services),
     ...createWorkflowWakeActivities(services),
     ...createSandboxLeaseActivities(services),

package/src/activities-turn.ts

@@ -12,6 +12,9 @@ function createTurnActivityServices(
   let servicesPromise: Promise<TurnActivityServices> | null = null;
   return async () => {
     servicesPromise ??= (async () => {
+      if (!dependencies.requestWorkerDrain) {
+        throw new Error("Turn activities require a host requestWorkerDrain lifecycle edge");
+      }
       const services = await shared();
       return {
         ...services,
@@ -20,6 +23,8 @@ function createTurnActivityServices(
           createProductionAgentRuntime({
             metrics: runtimeMetricsHooksForObservability(services.observability),
           }),
+        requestWorkerDrain: dependencies.requestWorkerDrain,
+        turnFinalizationTimeoutMs: dependencies.turnFinalizationTimeoutMs,
         summarizeContextForCompaction:
           dependencies.summarizeContextForCompaction ?? summarizeForCompaction,
       };

package/src/activities.ts

@@ -69,6 +69,12 @@ export function createActivityTestHarness(dependencies: ActivityDependencies = {
           createProductionAgentRuntime({
             metrics: runtimeMetricsHooksForObservability(common.observability),
           }),
+        requestWorkerDrain:
+          dependencies.requestWorkerDrain ??
+          (() => {
+            throw new Error("Test host must provide requestWorkerDrain for stalled cleanup");
+          }),
+        turnFinalizationTimeoutMs: dependencies.turnFinalizationTimeoutMs,
         summarizeContextForCompaction:
           dependencies.summarizeContextForCompaction ?? summarizeForCompaction,
         documentServices: dependencies.documentServices ?? createDocumentServices(common.settings),
@@ -99,6 +105,8 @@ export const persistSessionAttemptQuiescence =
   defaultControlActivities.persistSessionAttemptQuiescence;
 export const reconcileSessionAttemptQuiescence =
   defaultControlActivities.reconcileSessionAttemptQuiescence;
+export const reconcileSettledSessionAttempt =
+  defaultControlActivities.reconcileSettledSessionAttempt;
 export const recoverDispatch = defaultControlActivities.recoverDispatch;
 export const recoverEscapedMcpTimeout = defaultControlActivities.recoverEscapedMcpTimeout;
 export const peekSessionWork = defaultControlActivities.peekSessionWork;
@@ -106,6 +114,7 @@ export const settleSessionInputWait = defaultControlActivities.settleSessionInpu
 export const expireSessionHumanInput = defaultControlActivities.expireSessionHumanInput;
 export const expireSessionInteractionIntervention =
   defaultControlActivities.expireSessionInteractionIntervention;
+export const expireScheduledRunHumanWait = defaultControlActivities.expireScheduledRunHumanWait;
 export const markSessionIdle = defaultControlActivities.markSessionIdle;
 export const dispatchScheduledTaskRun = defaultControlActivities.dispatchScheduledTaskRun;
 export const dispatchAutomationRun = defaultControlActivities.dispatchAutomationRun;
@@ -116,6 +125,9 @@ export const maybeContinueGoal = defaultControlActivities.maybeContinueGoal;
 export const getCodexCapacityWait = defaultControlActivities.getCodexCapacityWait;
 export const reconcileCodexCapacityWait = defaultControlActivities.reconcileCodexCapacityWait;
 export const prepareSandboxLeaseSweep = defaultControlActivities.prepareSandboxLeaseSweep;
+export const listDueBrowserCheckpoints = defaultControlActivities.listDueBrowserCheckpoints;
+export const checkpointBrowserBeforeDeadline =
+  defaultControlActivities.checkpointBrowserBeforeDeadline;
 export const drainSandboxLease = defaultControlActivities.drainSandboxLease;
 export const maintainSandboxLeaseSweep = defaultControlActivities.maintainSandboxLeaseSweep;
 export const reapSandboxLeases = defaultControlActivities.reapSandboxLeases;
@@ -124,6 +136,7 @@ export const recoverVideoGenerationWorkflows =
   defaultControlActivities.recoverVideoGenerationWorkflows;
 export const maintainRetainedScreenshots = defaultControlActivities.maintainRetainedScreenshots;
 export const maintainBrowserStateArtifacts = defaultControlActivities.maintainBrowserStateArtifacts;
+export const reconcileRecentModelCallFacts = defaultControlActivities.reconcileRecentModelCallFacts;
 export const maintainSiteAuthConnections = defaultControlActivities.maintainSiteAuthConnections;
 export const dispatchSessionWorkflowWakes = defaultControlActivities.dispatchSessionWorkflowWakes;
 export const verifyRigChange = defaultControlActivities.verifyRigChange;

package/src/activity-services.ts

@@ -1,11 +1,20 @@
-import { dbSearchPath, getSettings, resolveNatsControlPlaneAuth } from "@opengeni/config";
-import { configureChildLifecycleNotices, createDb } from "@opengeni/db";
+import {
+  codeSearchDeploymentPolicy,
+  dbSearchPath,
+  getSettings,
+  resolveNatsControlPlaneAuth,
+} from "@opengeni/config";
+import {
+  configureChildLifecycleNotices,
+  configureCodeSearchDeploymentPolicy,
+  createDb,
+} from "@opengeni/db";
 import { createNatsEventBus } from "@opengeni/events";
 import { createObservability } from "@opengeni/observability";
 import { resolveCatalogSettings } from "@opengeni/core";
 import { createObjectStorage } from "@opengeni/storage";
 import type { ActivityDependencies, SharedActivityServices } from "./activities/types";
-import { observabilityEventLogger } from "./observability-metrics";
+import { observabilityEventBusOptions } from "./observability-metrics";
 import { buildPersonalGitHubGitCredentials } from "./personal-github-git-credentials";
 import { createStandaloneConnectionCredentialsPort } from "./pr-review-credentials";
 
@@ -40,6 +49,9 @@ export function createSharedActivityServices(
       // Child lifecycle notice producers are process-global in @opengeni/db;
       // install the boot-validated rollout flag once for this worker.
       configureChildLifecycleNotices({ enabled: settings.childLifecycleNoticesEnabled });
+      // Child, scheduled and automation sessions created here freeze their
+      // code_search decision from the same deployment policy as the API.
+      configureCodeSearchDeploymentPolicy(codeSearchDeploymentPolicy(settings));
       return {
         settings: resolvedSettings,
         catalogSourceSettings: settings,
@@ -51,7 +63,7 @@ export function createSharedActivityServices(
             controlPlaneAuth
               ? { user: controlPlaneAuth.user, pass: controlPlaneAuth.password }
               : undefined,
-            { logger: observabilityEventLogger(observability) },
+            observabilityEventBusOptions(observability),
           )),
         objectStorage: dependencies.objectStorage ?? createObjectStorage(settings),
         observability,

package/src/browser-deadline-checkpoint-contract.ts

@@ -0,0 +1,5 @@
+export const BROWSER_DEADLINE_CHECKPOINT_SWEEP_ID = "opengeni-browser-deadline-checkpoints-v1";
+const QUEUE_SUFFIX = "-browser-checkpoint-v1";
+export function browserDeadlineCheckpointTaskQueue(base: string): string {
+  return base.endsWith(QUEUE_SUFFIX) ? base : `${base}${QUEUE_SUFFIX}`;
+}

package/src/editable-artifact-hint-broker.ts

@@ -161,6 +161,9 @@ export async function connectEditableArtifactHintBroker(
     name,
     reconnect: true,
     maxReconnectAttempts: -1,
+    // Same policy as the event bus: a broker or auth-callout restart must not
+    // permanently close this connection after two identical auth errors.
+    ignoreAuthErrorAbort: true,
     reconnectTimeWait: 2_000,
     reconnectJitter: 1_000,
     reconnectJitterTLS: 1_000,

package/src/editable-artifact-materializer-service.ts

@@ -1,4 +1,8 @@
-import { dbSearchPath, getSettings, type Settings } from "@opengeni/config";
+import {
+  dbSearchPath,
+  getArtifactMaterializerSettings,
+  type ArtifactMaterializerSettings,
+} from "@opengeni/config";
 import {
   createDb,
   dbSql,
@@ -77,7 +81,7 @@ export type CreateEditableArtifactMaterializerServiceInput = Readonly<{
 }>;
 
 export type ProductionEditableArtifactMaterializerServiceOptions = Readonly<{
-  settings: Settings;
+  settings: ArtifactMaterializerSettings;
   /** Dedicated DSN; never defaults to settings.databaseUrl. */
   databaseUrl: string;
   declaredDatabaseRole: string;
@@ -671,7 +675,7 @@ export async function createMaterializerSidecarFromEnvironment(
 }> | null> {
   const sidecar = readEditableArtifactMaterializerSidecarEnvironment(environment);
   if (!sidecar) return null;
-  const settings = getSettings();
+  const settings = getArtifactMaterializerSettings(environment);
   const service = await createProductionEditableArtifactMaterializerService({
     settings,
     databaseUrl: sidecar.databaseUrl,

package/src/editable-artifact-outbox-service.ts

@@ -1,8 +1,8 @@
 import {
   dbSearchPath,
-  getSettings,
+  getArtifactOutboxSettings,
   resolveNatsControlPlaneAuth,
-  type Settings,
+  type ArtifactOutboxSettings,
 } from "@opengeni/config";
 import type { EditableArtifactOutboxDispatchSummary } from "@opengeni/core";
 import { createObservability, type Observability } from "@opengeni/observability";
@@ -51,7 +51,7 @@ export type CreateEditableArtifactOutboxServiceInput = Readonly<{
 }>;
 
 export type ProductionEditableArtifactOutboxServiceOptions = Readonly<{
-  settings: Settings;
+  settings: ArtifactOutboxSettings;
   databaseUrl: string;
   declaredDatabaseRole: string;
   natsUrl: string;
@@ -360,7 +360,7 @@ export async function createOutboxSidecarFromEnvironment(
 ): Promise<Readonly<{ service: EditableArtifactOutboxService; httpPort: number }> | null> {
   const sidecar = readEditableArtifactOutboxSidecarEnvironment(environment);
   if (!sidecar) return null;
-  const settings = getSettings();
+  const settings = getArtifactOutboxSettings(environment);
   const controlPlaneAuth = resolveNatsControlPlaneAuth(settings);
   const natsAuth: EditableArtifactHintNatsAuth = controlPlaneAuth
     ? {

package/src/github-rest-mcp.ts

@@ -113,7 +113,7 @@ export async function buildGitHubRestMcpForTurn(input: {
         resolveAuthority: appResolver,
       }),
     });
-    configs.push(internalMcpConfig(GITHUB_REST_MCP_APP_SERVER_ID, "GitHub — OpenGeni bot"));
+    configs.push(internalMcpConfig(GITHUB_REST_MCP_APP_SERVER_ID, "GitHub — Opengeni bot"));
     toolRefs.push({ kind: "mcp", id: GITHUB_REST_MCP_APP_SERVER_ID });
     connectorBindings.push(
       ...githubConnectorBindings(GITHUB_REST_MCP_APP_SERVER_ID, appRepositories),
@@ -519,7 +519,6 @@ function exactPersonalDelegation(
     delegation.providerDomain !== "github.com" ||
     delegation.kind !== "oauth2" ||
     !delegation.originWorkspaceId ||
-    !delegation.userDelegation ||
     !delegation.personalGitHubRepositorySelection
   ) {
     throw new GitHubRestAuthorityError("Personal GitHub delegation is unavailable");

package/src/host-export-pump.ts

@@ -1,4 +1,4 @@
-import type { HostEventSink, HostUsageSink } from "@opengeni/contracts";
+import type { HostEventSink, HostLifecycleFactSink, HostUsageSink } from "@opengeni/contracts";
 import {
   acknowledgeHostExportBatch,
   claimHostExportBatch,
@@ -35,6 +35,8 @@ export type HostExportPumpOptions = {
   db: Database;
   eventSink?: HostEventSink;
   usageSink?: HostUsageSink;
+  /** Content-free per-person product lifecycle facts (`lifecycle_fact`). */
+  lifecycleSink?: HostLifecycleFactSink;
   observability?: Observability;
   instanceId?: string;
   pollIntervalMs?: number;
@@ -77,7 +79,7 @@ export type HostExportPump = {
  * keys. Sink implementations must therefore deduplicate those keys.
  */
 export function createHostExportPump(options: HostExportPumpOptions): HostExportPump {
-  if (!options.eventSink && !options.usageSink) {
+  if (!options.eventSink && !options.usageSink && !options.lifecycleSink) {
     throw new Error("createHostExportPump requires at least one host sink");
   }
   const instanceId = validateInstanceId(
@@ -102,7 +104,9 @@ export function createHostExportPump(options: HostExportPumpOptions): HostExport
   const configuredConsumer = (kind: HostExportKind): string | null =>
     kind === "session_event"
       ? (options.eventSink?.consumerId ?? null)
-      : (options.usageSink?.consumerId ?? null);
+      : kind === "usage_event"
+        ? (options.usageSink?.consumerId ?? null)
+        : (options.lifecycleSink?.consumerId ?? null);
 
   const recordResult = (result: HostExportDrainResult, durationSeconds: number) => {
     const labels = { kind: result.kind, outcome: result.outcome };
@@ -242,7 +246,7 @@ export function createHostExportPump(options: HostExportPumpOptions): HostExport
           ...common,
         });
         if (batch) return await deliverClaim(batch.events.length, () => sink.deliverEvents(batch));
-      } else {
+      } else if (kind === "usage_event") {
         const sink = options.usageSink;
         if (!sink) return { kind, outcome: "not_configured" };
         const batch = await claimHostExportBatch(options.db, {
@@ -250,6 +254,16 @@ export function createHostExportPump(options: HostExportPumpOptions): HostExport
           ...common,
         });
         if (batch) return await deliverClaim(batch.events.length, () => sink.deliverUsage(batch));
+      } else {
+        const sink = options.lifecycleSink;
+        if (!sink) return { kind, outcome: "not_configured" };
+        const batch = await claimHostExportBatch(options.db, {
+          kind,
+          ...common,
+        });
+        if (batch) {
+          return await deliverClaim(batch.events.length, () => sink.deliverLifecycleFacts(batch));
+        }
       }
     } catch (error) {
       return await settleFailure(error);
@@ -276,6 +290,7 @@ export function createHostExportPump(options: HostExportPumpOptions): HostExport
     const results: HostExportDrainResult[] = [];
     if (options.eventSink) results.push(await drainKind("session_event"));
     if (options.usageSink) results.push(await drainKind("usage_event"));
+    if (options.lifecycleSink) results.push(await drainKind("lifecycle_fact"));
     return results;
   };
 
@@ -326,9 +341,16 @@ export function createHostExportPump(options: HostExportPumpOptions): HostExport
               consumerId: options.usageSink.consumerId,
             });
           }
+          if (options.lifecycleSink) {
+            await registerHostExportConsumer(scoped, {
+              kind: "lifecycle_fact",
+              consumerId: options.lifecycleSink.consumerId,
+            });
+          }
         });
         if (options.eventSink) retiringKinds.delete("session_event");
         if (options.usageSink) retiringKinds.delete("usage_event");
+        if (options.lifecycleSink) retiringKinds.delete("lifecycle_fact");
         running = true;
         loopPromise = (async () => {
           while (true) {

package/src/host-export.ts

@@ -16,6 +16,9 @@ export type {
   HostEventExport,
   HostEventExportBatch,
   HostEventSink,
+  HostLifecycleFactExport,
+  HostLifecycleFactExportBatch,
+  HostLifecycleFactSink,
   HostUsageExport,
   HostUsageExportBatch,
   HostUsageSink,

package/src/http.ts

@@ -120,6 +120,7 @@ export async function runReadinessChecks(
 export function dbReadyCheck(
   db: Database,
   posture?: RuntimeDatabasePostureOptions,
+  afterDatabaseReady?: () => Promise<void>,
 ): () => Promise<void> {
   let inFlight: Promise<void> | undefined;
   return () => {
@@ -130,9 +131,10 @@ export function dbReadyCheck(
     inFlight = (async () => {
       if (posture) {
         await assertRuntimeDatabasePosture(db, posture);
-        return;
+      } else {
+        await db.execute(dbSql`select 1`);
       }
-      await db.execute(dbSql`select 1`);
+      await afterDatabaseReady?.();
     })().finally(() => {
       inFlight = undefined;
     });