@humwick/server 0.0.0-stage → 0.130.1

package/src/provider-config-store.ts

@@ -0,0 +1,308 @@
+import { writeChildEnv } from "@humwick/sdk/env";
+import { existsSync, readdirSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { ValidationError, listOrchestrators } from "./db";
+import { isSecretEnvKey } from "./db/provider-config-secrets";
+import { getConfig, listConfig, setConfig } from "./config-store";
+import { localOrchestratorIdFromEnv, providerConfigHomeFromEnv } from "./config";
+import { cleanString, cleanStringArray, optionalEnum } from "./validation";
+import { emitConfigChanged } from "./sse";
+import {
+  PROVIDER_CONFIG_NAMESPACE,
+  validateSettingValue,
+} from "./settings/registry";
+import {
+  getProviderSettingsDeclaration,
+  listProviderSettingsDeclarations,
+  providerConfigDefaults,
+  registerDeclaredProviderConfigSetting,
+} from "./settings/modules";
+import { ACTIVE_TURN_MESSAGE_DELIVERY_VALUES } from "../runner/src/adapter";
+import { defaultProviderConfig, loadProviderConfig as loadLocalProviderConfig } from "../runner/src/config";
+import { SPAWN_PROVIDERS, isRecord, type ConfigEntry, type SpawnProvider } from "@humwick/sdk";
+import type { ProviderConfig } from "../runner/src/adapter";
+
+export const VALID_PROVIDER_CONFIGS = SPAWN_PROVIDERS;
+
+/** Sentinel GET masking uses for secret env values — PUT treats it as "keep existing". */
+export const MASKED_SECRET_SENTINEL = "********";
+
+type ProviderConfigProvider = string;
+type ProviderConfigEntry = ConfigEntry<ProviderConfig>;
+
+function defaultProviderConfigHost(): string {
+  return localOrchestratorIdFromEnv() ?? hostname();
+}
+
+function providerConfigKey(host: string, provider: string): string {
+  return `${normalizeProviderConfigHost(host)}/${normalizeProviderConfigProvider(provider)}`;
+}
+
+function parseProviderConfigKey(key: string): { host: string; provider: ProviderConfigProvider } | null {
+  const slash = key.lastIndexOf("/");
+  if (slash <= 0 || slash === key.length - 1) return null;
+  const host = cleanString(key.slice(0, slash), "host", { required: true, max: 120 })!;
+  const provider = cleanString(key.slice(slash + 1), "provider", { required: true, max: 80 })!;
+  return getProviderSettingsDeclaration(provider) ? { host, provider } : null;
+}
+
+export function ensureProviderConfigDescriptors(extraKeys: string[] = []): void {
+  const keys = new Set<string>();
+  const providerDeclarations = listProviderSettingsDeclarations();
+  for (const entry of listConfig(PROVIDER_CONFIG_NAMESPACE)) keys.add(entry.key);
+  for (const orchestrator of listOrchestrators()) {
+    for (const declaration of providerDeclarations) keys.add(providerConfigKey(orchestrator.id, declaration.provider));
+  }
+  for (const declaration of providerDeclarations) keys.add(providerConfigKey(defaultProviderConfigHost(), declaration.provider));
+  for (const key of extraKeys) keys.add(key);
+
+  for (const key of keys) {
+    const parsed = parseProviderConfigKey(key);
+    if (!parsed) continue;
+    registerDeclaredProviderConfigSetting({
+      host: parsed.host,
+      provider: parsed.provider,
+    });
+  }
+}
+
+export function getProviderConfigEntry(provider: string, host = defaultProviderConfigHost()): ProviderConfigEntry {
+  const cleanProvider = normalizeProviderConfigProvider(provider);
+  const cleanHost = normalizeProviderConfigHost(host);
+  const key = providerConfigKey(cleanHost, cleanProvider);
+  ensureProviderConfigDescriptors([key]);
+  const entry = getConfig<ProviderConfig>(PROVIDER_CONFIG_NAMESPACE, key);
+  if (entry) return { ...entry, value: mergeProviderConfig(cleanProvider, entry.value) };
+  return {
+    namespace: PROVIDER_CONFIG_NAMESPACE,
+    key,
+    value: providerConfigDefaults(cleanProvider),
+    version: 0,
+    updatedAt: "default",
+    updatedBy: "system",
+  };
+}
+
+export function listProviderConfigEntries(host = defaultProviderConfigHost()): Record<SpawnProvider, ProviderConfigEntry> {
+  return Object.fromEntries(
+    VALID_PROVIDER_CONFIGS.map((provider) => [provider, getProviderConfigEntry(provider, host)]),
+  ) as Record<SpawnProvider, ProviderConfigEntry>;
+}
+
+export function setProviderConfig(
+  provider: string,
+  value: unknown,
+  opts: { host?: string; updatedBy?: string } = {},
+): ProviderConfigEntry {
+  const cleanProvider = normalizeProviderConfigProvider(provider);
+  const host = normalizeProviderConfigHost(opts.host ?? defaultProviderConfigHost());
+  const normalized = cleanProviderConfig(cleanProvider, resolveMaskedEnvSentinels(value, host, cleanProvider));
+  const key = providerConfigKey(host, cleanProvider);
+  ensureProviderConfigDescriptors([key]);
+  const validation = validateSettingValue(PROVIDER_CONFIG_NAMESPACE, key, normalized);
+  if (!validation.valid) throw new ValidationError(validation.errors.join("; "));
+  return setConfig(PROVIDER_CONFIG_NAMESPACE, key, normalized, opts.updatedBy) as ProviderConfigEntry;
+}
+
+export function providerConfigPublic(entry: ProviderConfigEntry, opts: { maskEnv?: boolean } = {}): Record<string, unknown> {
+  const parsed = parseProviderConfigKey(entry.key);
+  return {
+    namespace: entry.namespace,
+    key: entry.key,
+    path: `config:${entry.namespace}/${entry.key}`,
+    host: parsed?.host,
+    provider: parsed?.provider,
+    version: entry.version,
+    updatedAt: entry.updatedAt,
+    updatedBy: entry.updatedBy,
+    command: entry.value.command,
+    defaultArgs: entry.value.defaultArgs,
+    env: opts.maskEnv === false ? entry.value.env : maskEnv(entry.value.env),
+    pluginDirs: entry.value.pluginDirs,
+    globalInstructionFiles: entry.value.globalInstructionFiles ?? [],
+    defaultCapabilities: entry.value.defaultCapabilities,
+    defaultApprovalMode: entry.value.defaultApprovalMode,
+    defaultTags: entry.value.defaultTags,
+    chatCaptureMode: entry.value.chatCaptureMode,
+    reasoningCapture: entry.value.reasoningCapture,
+    activeTurnMessageDelivery: entry.value.activeTurnMessageDelivery,
+    headless: entry.value.headless,
+  };
+}
+
+/**
+ * Idempotently seed central provider-config rows for `host` from raw per-provider
+ * config objects (#465). A real stored row (version >= 1) always wins — a stale
+ * local file never clobbers it. Unknown providers and malformed bodies are skipped.
+ * This is the server-authority write path: callers are in-process (local migration
+ * or the orchestrator command-bus result handler), so no HTTP scope is required.
+ */
+export function seedProviderConfigs(
+  host: string,
+  rawByProvider: Record<string, unknown>,
+  opts: { legacyHost?: string } = {},
+): ProviderConfigEntry[] {
+  const seeded: ProviderConfigEntry[] = [];
+  const cleanHost = normalizeProviderConfigHost(host);
+  const legacyHost = opts.legacyHost ? normalizeProviderConfigHost(opts.legacyHost) : undefined;
+  for (const [provider, raw] of Object.entries(rawByProvider)) {
+    if (!VALID_PROVIDER_CONFIGS.includes(provider as SpawnProvider)) continue;
+    const key = providerConfigKey(cleanHost, provider);
+    if (getConfig(PROVIDER_CONFIG_NAMESPACE, key)) continue;
+    // Stable-id rows supersede legacy hostname rows. Until a real id row exists,
+    // preserve the central hostname value over a possibly stale local file.
+    const legacy = legacyHost && legacyHost !== cleanHost
+      ? getConfig<ProviderConfig>(PROVIDER_CONFIG_NAMESPACE, providerConfigKey(legacyHost, provider))
+      : null;
+    // Shallow-merge defaults so a partial local file (e.g. missing `command`)
+    // still validates; the relay owns the schema, the reporter stays dumb.
+    const value = legacy?.value ?? { ...providerConfigDefaults(provider), ...(isRecord(raw) ? raw : {}) };
+    try {
+      const entry = setProviderConfig(provider, value, { host: cleanHost, updatedBy: `migration:${cleanHost}` });
+      emitConfigChanged(entry.namespace, entry.key, entry.version);
+      seeded.push(entry);
+    } catch {
+      // A single invalid provider config shouldn't abort seeding the rest.
+    }
+  }
+  return seeded;
+}
+
+/**
+ * Accept an orchestrator migration result at the provider-config boundary. This
+ * owns the stable-id/legacy-hostname resolution together so command routes do
+ * not re-parse or accidentally bypass the migration authority rules.
+ */
+export function seedMigratedProviderConfigs(result: unknown): { host: string; seeded: ProviderConfigEntry[] } | null {
+  if (!isRecord(result)) return null;
+  const host = cleanString(result.host, "result.host", { max: 120 });
+  const hostname = cleanString(result.hostname, "result.hostname", { max: 120 });
+  const configs = isRecord(result.configs) ? result.configs : undefined;
+  if (!host || !configs) return null;
+  return { host, seeded: seedProviderConfigs(host, configs, { legacyHost: hostname }) };
+}
+
+export function migrateLocalProviderConfigs(home = humwickHome(), host = defaultProviderConfigHost()): ProviderConfigEntry[] {
+  const dir = join(home, "providers");
+  if (!existsSync(dir)) return [];
+  const raw: Record<string, unknown> = {};
+  for (const file of readdirSync(dir)) {
+    const provider = file.endsWith(".json") ? file.slice(0, -".json".length) : "";
+    if (!VALID_PROVIDER_CONFIGS.includes(provider as SpawnProvider)) continue;
+    raw[provider] = loadLocalProviderConfig(provider, home);
+  }
+  return seedProviderConfigs(host, raw);
+}
+
+function normalizeProviderConfigHost(host: string): string {
+  return cleanString(host, "host", { required: true, max: 120 })!;
+}
+
+function normalizeProviderConfigProvider(provider: string): ProviderConfigProvider {
+  const clean = cleanString(provider, "provider", { required: true, max: 80 })!;
+  if (!getProviderSettingsDeclaration(clean)) {
+    throw new ValidationError(`provider must be one of: ${listProviderSettingsDeclarations().map((d) => d.provider).join(", ")}`);
+  }
+  return clean;
+}
+
+function cleanProviderConfig(provider: string, value: unknown): ProviderConfig {
+  if (!isRecord(value)) throw new ValidationError("provider config body must be an object");
+  const defaults = providerConfigDefaults(provider);
+  const headless = isRecord(value.headless) ? value.headless : {};
+  return {
+    command: cleanString(value.command, "command", { required: true, max: 500 })!,
+    defaultArgs: cleanStringArray(value.defaultArgs, "defaultArgs", { itemMax: 80, maxItems: 50 }) ?? defaults.defaultArgs,
+    env: cleanEnvRecord(value.env),
+    pluginDirs: cleanStringArray(value.pluginDirs, "pluginDirs", { itemMax: 80, maxItems: 50 }) ?? defaults.pluginDirs,
+    globalInstructionFiles: cleanStringArray(value.globalInstructionFiles, "globalInstructionFiles", { itemMax: 80, maxItems: 10 }) ?? defaults.globalInstructionFiles,
+    defaultCapabilities: cleanStringArray(value.defaultCapabilities, "defaultCapabilities", { itemMax: 80, maxItems: 50 }) ?? defaults.defaultCapabilities,
+    defaultApprovalMode: cleanString(value.defaultApprovalMode, "defaultApprovalMode", { max: 80 }) ?? defaults.defaultApprovalMode,
+    defaultTags: cleanStringArray(value.defaultTags, "defaultTags", { itemMax: 80, maxItems: 50 }) ?? defaults.defaultTags,
+    chatCaptureMode: (optionalEnum(value.chatCaptureMode, "chatCaptureMode", ["final", "full"]) ?? defaults.chatCaptureMode) as "final" | "full",
+    reasoningCapture: value.reasoningCapture === undefined ? defaults.reasoningCapture ?? true : cleanBoolean(value.reasoningCapture, "reasoningCapture"),
+    // #2539 Phase A — optional: absent resolves through the OWNING adapter's default (codex
+    // adapter → steer, others → defer). `"defer"` is the operational kill switch for soft-steer.
+    activeTurnMessageDelivery: optionalEnum(value.activeTurnMessageDelivery, "activeTurnMessageDelivery", ACTIVE_TURN_MESSAGE_DELIVERY_VALUES),
+    headless: {
+      tmuxPrefix: cleanString(headless.tmuxPrefix, "headless.tmuxPrefix", { max: 120 }) ?? defaults.headless.tmuxPrefix,
+      shutdownTimeoutMs: cleanPositiveInt(headless.shutdownTimeoutMs, "headless.shutdownTimeoutMs") ?? defaults.headless.shutdownTimeoutMs,
+    },
+  };
+}
+
+function mergeProviderConfig(provider: string, value: Partial<ProviderConfig>): ProviderConfig {
+  const defaults = providerConfigDefaults(provider);
+  return cleanProviderConfig(provider, { ...defaults, ...value, headless: { ...defaults.headless, ...value.headless } });
+}
+
+function cleanEnvRecord(value: unknown): Record<string, string> {
+  if (value === undefined) return {};
+  if (!isRecord(value)) throw new ValidationError("env must be an object");
+  const env: Record<string, string> = {};
+  for (const [key, item] of Object.entries(value)) {
+    const cleanKey = cleanString(key, "env key", { required: true, max: 120 })!;
+    if (typeof item !== "string") throw new ValidationError(`env.${cleanKey} must be a string`);
+    writeChildEnv(env, { [cleanKey]: item });
+  }
+  return env;
+}
+
+function cleanBoolean(value: unknown, field: string): boolean {
+  if (typeof value !== "boolean") throw new ValidationError(`${field} must be a boolean`);
+  return value;
+}
+
+function cleanPositiveInt(value: unknown, field: string): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new ValidationError(`${field} must be a positive integer`);
+  }
+  return value;
+}
+
+function maskEnv(env: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    result[key] = isSecretEnvKey(key) && !value.startsWith("$env:") ? MASKED_SECRET_SENTINEL : value;
+  }
+  return result;
+}
+
+/**
+ * #2604 — treat the masked sentinel as "keep the existing stored value".
+ * GET masks secret env values as `********`; a naive GET→merge→PUT would
+ * otherwise persist the literal mask and destroy the real credential.
+ * A real (non-sentinel) value updates as today; an omitted key still removes.
+ * The sentinel is NEVER persisted: on a secret-class key with no existing
+ * stored value (fresh row, or a genuinely-new key) it is dropped, not written.
+ * Only secret-class keys (same predicate maskEnv uses) are resolved — an
+ * intentional literal `********` on a non-secret key passes through verbatim.
+ * Accepted edge: a real secret whose value literally is `********` cannot be
+ * stored via PUT (it resolves to keep-existing/drop) — safe because persisting
+ * the mask literal is never intended, and the value is idempotent anyway.
+ */
+function resolveMaskedEnvSentinels(value: unknown, host: string, provider: string): unknown {
+  if (!isRecord(value) || !isRecord(value.env)) return value;
+  const existing = getConfig<ProviderConfig>(
+    PROVIDER_CONFIG_NAMESPACE,
+    providerConfigKey(host, provider),
+  )?.value.env ?? {};
+  let changed = false;
+  const env: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value.env)) {
+    if (item === MASKED_SECRET_SENTINEL && isSecretEnvKey(key)) {
+      changed = true;
+      if (existing[key] !== undefined) writeChildEnv(env, { [key]: existing[key] });
+      // else: no stored value to keep — drop the key rather than persist the mask.
+    } else {
+      writeChildEnv(env, { [key]: item });
+    }
+  }
+  return changed ? { ...value, env } : value;
+}
+
+function humwickHome(): string {
+  return providerConfigHomeFromEnv();
+}

package/src/provider-enablement.ts

@@ -0,0 +1,36 @@
+// #2656 — the operator's runtime per-provider enable/disable switch (no deploy). Stored as one
+// `config` row per provider (namespace `provider-enablement`, key = provider id) so history and
+// the `config.changed` SSE come for free. This module is a DB-free leaf holding the write-side
+// validator (config-store imports it); provider-catalog-store reads the rows to stamp the
+// effective catalog — the ONLY place a provider's effective-disabled state is derived.
+import { PROVIDER_ENABLEMENT_NAMESPACE, SPAWN_PROVIDERS, cleanString, isRecord } from "@humwick/sdk";
+import type { ProviderEnablementSetting } from "@humwick/sdk/provider-catalog";
+import { ValidationError } from "./db/connection.ts";
+
+export { PROVIDER_ENABLEMENT_NAMESPACE };
+
+/** Write-side normalizer (every config write path funnels through config-store's normalizeValue). */
+export function validateProviderEnablement(key: string, value: unknown, now = Date.now()): ProviderEnablementSetting {
+  if (!(SPAWN_PROVIDERS as readonly string[]).includes(key)) {
+    throw new ValidationError(`provider must be one of: ${SPAWN_PROVIDERS.join(", ")}`);
+  }
+  if (!isRecord(value)) throw new ValidationError("provider enablement value must be an object");
+  if (typeof value.enabled !== "boolean") throw new ValidationError("enabled must be a boolean");
+  // Re-enabling drops the disable metadata; model settings/defaults live elsewhere and are untouched.
+  if (value.enabled) return { enabled: true };
+  const reason = cleanString(value.reason, "reason", { max: 500 });
+  const disabledUntil = cleanDisabledUntil(value.disabledUntil, now);
+  return {
+    enabled: false,
+    ...(disabledUntil !== undefined ? { disabledUntil } : {}),
+    ...(reason ? { reason } : {}),
+  };
+}
+
+function cleanDisabledUntil(value: unknown, now: number): number | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  const at = typeof value === "number" ? value : typeof value === "string" ? Date.parse(value) : Number.NaN;
+  if (!Number.isSafeInteger(at) || at <= 0) throw new ValidationError("disabledUntil must be an epoch-ms timestamp or ISO date");
+  if (at <= now) throw new ValidationError("disabledUntil must be in the future");
+  return at;
+}

package/src/provider-home-gc.ts

@@ -0,0 +1,58 @@
+// Server-side provider-home GC adapter (#1256, #2547). The reaping ENGINE lives in the SDK
+// (@humwick/sdk/provider-home-gc) so the SAME quarantine/tombstone pipeline runs in two
+// venues: HERE in REGISTRY mode — the relay server's maintenance job, where the server's
+// agent table is the fleet liveness authority — and on every orchestrator host in HOST mode
+// (scripts/provider-home-gc.ts, run detached by the orchestrator scheduler), where a
+// host-local live-holder probe replaces the registry. #2547: only the server ever ran the
+// reaper, so orchestrator hosts without a co-located relay accumulated 43G/801 dead homes —
+// the exact #2283 artifact-checkout pattern.
+//
+// The full safety argument (spawn-side reclaim, quarantine-then-delete, crash safety,
+// never-delete discipline) lives on the engine. This adapter only binds the server's own
+// inputs: config knobs and the fleet registry view.
+import { providerHomeRootFromEnv } from "../runner/src/config";
+import { providerHomeOwnerId } from "../runner/src/provider-home-marker";
+import {
+  providerHomeAgeGcEnabled,
+  providerHomeGcEnabled,
+  providerHomeGraceMs,
+  providerHomeOrphanTtlMs,
+  providerHomeQuarantineMs,
+} from "./config";
+import { listAgents } from "./db";
+import { runProviderHomeGc, type ProviderHomeGcAgent, type ProviderHomeGcResult } from "@humwick/sdk/provider-home-gc";
+
+export type { ProviderHomeGcResult };
+
+/**
+ * Scheduled reaper (maintenance job), REGISTRY mode. Runs both passes over a single
+ * top-of-scan snapshot of the provider-home root:
+ *   - Pass A quarantines newly-eligible orphans (rename → `.reaping-*` tombstone; NO rm).
+ *   - Pass B deletes tombstones that have sat quarantined past the quarantine TTL and still
+ *     have no live owner (stage → `.deleting-*`, then rm), and sweeps crash-leftover
+ *     `.deleting-*` dirs.
+ * A tombstone created by THIS run's Pass A is NOT in the scanned `tombstones` list (that
+ * list is the disk state read before Pass A ran), so a home is never quarantined and
+ * deleted in the same run — the minimum one-run gap IS the quarantine, independent of the
+ * TTL value.
+ */
+export async function reapProviderHomes(now: number = Date.now(), signal?: AbortSignal): Promise<ProviderHomeGcResult> {
+  return runProviderHomeGc({
+    root: providerHomeRootFromEnv(),
+    now,
+    signal,
+    ownerId: providerHomeOwnerId(),
+    graceMs: providerHomeGraceMs(),
+    orphanTtlMs: providerHomeOrphanTtlMs(),
+    quarantineTtlMs: providerHomeQuarantineMs(),
+    reapEnabled: providerHomeGcEnabled(),
+    ageGcEnabled: providerHomeAgeGcEnabled(),
+    registry: { list: listRegisteredAgents },
+  });
+}
+
+/** The engine's registry view over the server's agent table — re-read on EVERY call so a
+ * fresh recheck can never be defeated by a stale top-of-scan snapshot (#1256 finding 1). */
+function listRegisteredAgents(): ProviderHomeGcAgent[] {
+  return listAgents();
+}

package/src/provider-model-seed.ts

@@ -0,0 +1,18 @@
+import { getConfig, setConfig } from "./config-store";
+import { seedProviderModelOverrides } from "./provider-catalog-store";
+import { reconcileClaudeCatalogSeeds } from "./db/claude-catalog-reconcile";
+import { VERSION } from "./config";
+import { errMessage } from "@humwick/sdk";
+
+// Stamp only after the transactional seed succeeds so a failure retries next boot.
+export function reconcileProviderModelSeed(): void {
+  try {
+    reconcileClaudeCatalogSeeds();
+    const stamp = `seed:${VERSION}`;
+    if (getConfig<string>("system", "provider-model-seed-version")?.value === stamp) return;
+    seedProviderModelOverrides(stamp);
+    setConfig("system", "provider-model-seed-version", stamp, "server-startup");
+  } catch (err) {
+    console.warn(`[provider-model-seed] skipped: ${errMessage(err)}`);
+  }
+}

package/src/provider-quota-async.ts

@@ -0,0 +1,152 @@
+// Main-thread facade for provider quota ingestion. It deliberately lives outside db/ because
+// post-commit delivery depends on the event/router graph, which itself reads the db barrel — so a
+// db-barrel module importing events/notification-router would close an import cycle (#498). Both the
+// async gateway facade and the synchronous in-process compatibility wrapper live here for that reason.
+import { getGateway, WriteIndeterminateError, type DbValue } from "./db/gateway.ts";
+import { randomUUID } from "node:crypto";
+import { upsertProviderQuotaInTx, type ProviderQuotaPostCommitEffect, type ProviderQuotaUpsertOpResult } from "./db/provider-quotas.ts";
+import { invalidateProviderQuotaMatrixCache } from "./db/provider-quota-matrix-cache.ts";
+import { emitRelayEvent, emitRelayEventAsync } from "./events.ts";
+import { routeNotification, type RouteNotificationInput } from "./notification-router.ts";
+import type { Message, ProviderQuotaRecord, ProviderQuotaUpdateInput } from "./types";
+
+/**
+ * Async provider-quota ingest through the writer gateway. The writer op persists quota + advisory + band
+ * state and builds the returned record INSIDE its transaction; after the writer ack (post-COMMIT) the
+ * facade delivers the rendered advisory effects in production order — emitRelayEvent then
+ * routeNotification per pair — error-isolated so a delivery fault never fails the committed write.
+ *
+ */
+export async function upsertProviderQuotaAsync(
+  input: ProviderQuotaUpdateInput,
+  options: { now?: number; requiredLeaseHolder?: string; /** Reuse after an indeterminate transport result. */ requestId?: string } = {},
+): Promise<ProviderQuotaUpsertOpResult> {
+  // Capture once before the first await. Re-submission after a lost ACK must reconcile the writer's
+  // original result (including occurrence ids), never re-run against advanced advisory state.
+  const requestId = options.requestId ?? randomUUID();
+  const args = {
+    input,
+    ...(options.now !== undefined ? { now: options.now } : {}),
+    ...(options.requiredLeaseHolder ? { requiredLeaseHolder: options.requiredLeaseHolder } : {}),
+  };
+  const writeOptions = { idempotencyKey: `provider-quota-upsert:${requestId}` };
+  let value: DbValue;
+  try {
+    value = await getGateway().write("providerQuotas.upsert", args, writeOptions);
+  } catch (error) {
+    if (!(error instanceof WriteIndeterminateError)) throw error;
+    value = await getGateway().write("providerQuotas.upsert", args, writeOptions);
+  }
+  // The op runs on the writer thread; the matrix cache lives on main (#1870 S5).
+  invalidateProviderQuotaMatrixCache();
+  if (!isProviderQuotaUpsertOpResult(value)) throw new Error("providerQuotas.upsert returned invalid result data");
+  // Durable effects reconcile from the upsert ledger on a replay, because a lost ACK may have
+  // happened before their separate writer jobs were submitted. Live fanout deliberately mirrors
+  // the historical sync path: at-most-once/best-effort, only for a fresh writer execution.
+  await deliverProviderQuotaEffectsAsync(value, { fanOut: Boolean(value.freshExecution) });
+  return value;
+}
+
+/**
+ * Synchronous in-process compatibility wrapper for direct callers and existing tests. Runs the writer
+ * body directly (no gateway hop) and fires the returned effects synchronously.
+ */
+export function upsertProviderQuota(input: ProviderQuotaUpdateInput, now = Date.now()): ProviderQuotaRecord {
+  const result = upsertProviderQuotaInTx(input, now);
+  invalidateProviderQuotaMatrixCache();
+  if (result.outcome.kind !== "stored") throw new Error("provider quota lease not held");
+  deliverProviderQuotaEffects(result, { isolate: false });
+  return result.outcome.record;
+}
+
+/** Fire each event+notification pair in production order; `isolate` logs (not throws) per-pair faults. */
+function deliverProviderQuotaEffects(result: ProviderQuotaUpsertOpResult, options: { isolate: boolean }): void {
+  for (const effect of result.advisory?.effects ?? []) {
+    if (options.isolate) {
+      try {
+        emitRelayEvent(effect.event);
+        if (effect.notification) routeNotification(effect.notification);
+      } catch (error) {
+        console.error("provider quota post-commit effect failed", error);
+      }
+    } else {
+      emitRelayEvent(effect.event);
+      if (effect.notification) routeNotification(effect.notification);
+    }
+  }
+}
+
+async function deliverProviderQuotaEffectsAsync(
+  result: ProviderQuotaUpsertOpResult,
+  options: { fanOut: boolean },
+): Promise<void> {
+  for (const effect of result.advisory?.effects ?? []) {
+    try {
+      // Every pair is serialized event → notification. Both backends route through keyed writer
+      // jobs: a caller retry of the same upsert result must fan out the one committed occurrence,
+      // not append a duplicate event/message in the in-process compatibility backend.
+      const effectKey = providerQuotaEffectKey(effect);
+      await emitRelayEventAsync(effect.event, { idempotencyKey: `${effectKey}:event`, fanOut: options.fanOut });
+      if (effect.notification) {
+        const notificationArgs = {
+          input: effect.notification as RouteNotificationInput,
+          now: effect.notification.emittedAt,
+        };
+        const notificationOpts = { critical: true, idempotencyKey: `${effectKey}:notification` };
+        let messages: Message[];
+        try {
+          messages = await getGateway().write("providerQuotas.routeNotification", notificationArgs, notificationOpts) as unknown as Message[];
+        } catch (error) {
+          if (!(error instanceof WriteIndeterminateError)) throw error;
+          messages = await getGateway().write("providerQuotas.routeNotification", notificationArgs, notificationOpts) as unknown as Message[];
+        }
+        for (const [messageIndex, message] of messages.entries()) {
+          await emitRelayEventAsync(
+            { type: "message.new", source: message.from, subject: String(message.id), data: message as unknown as Record<string, unknown> },
+            { idempotencyKey: `${effectKey}:message:${messageIndex}`, fanOut: options.fanOut },
+          );
+        }
+      }
+    } catch (error) {
+      console.error("provider quota post-commit effect failed", error);
+    }
+  }
+}
+
+/**
+ * Stable across a facade retry, yet unique for every logical rendered post-commit effect.
+ *
+ * The writer persists a monotonic occurrence id in the same transaction as the transition. Event
+ * payloads and recipient lists are presentation data, not occurrence identity: identical payloads
+ * can legitimately recur after #738 state loss or as fleet membership changes.
+ */
+function providerQuotaEffectKey(effect: ProviderQuotaPostCommitEffect): string {
+  return `provider-quota:occurrence:${effect.occurrenceId}`;
+}
+
+function isDbValue(value: unknown): value is DbValue {
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") return true;
+  if (Array.isArray(value)) return value.every(isDbValue);
+  if (!value || typeof value !== "object") return false;
+  // Only PLAIN objects survive the structured-clone seam as data; a class instance (Date, Map, a domain
+  // class) is not a DbValue even if its enumerable values happen to be clone-safe. Reject by prototype.
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return false;
+  return Object.values(value).every(isDbValue);
+}
+
+function isProviderQuotaUpsertOpResult(value: DbValue): value is ProviderQuotaUpsertOpResult & DbValue {
+  if (!isDbValue(value) || !value || typeof value !== "object" || Array.isArray(value) || !("outcome" in value)) return false;
+  const outcome = value.outcome;
+  if (!outcome || typeof outcome !== "object" || Array.isArray(outcome) || !("kind" in outcome)) return false;
+  if (outcome.kind === "lease-not-held") return true;
+  if (outcome.kind !== "stored" || !("record" in outcome)) return false;
+  const advisory = value.advisory;
+  const advisoryRecord = advisory && typeof advisory === "object" && !Array.isArray(advisory) && !(advisory instanceof Uint8Array)
+    ? advisory as Record<string, unknown>
+    : undefined;
+  return advisory === null || Boolean(advisoryRecord
+    && typeof advisoryRecord.advisoryState === "string" && typeof advisoryRecord.bandState === "string"
+    && Array.isArray(advisoryRecord.effects) && advisoryRecord.effects.every((effect: unknown) => effect && typeof effect === "object" && !Array.isArray(effect)
+      && "event" in effect && isDbValue(effect)));
+}

package/src/provider-quota-config-store.ts

@@ -0,0 +1,60 @@
+// Per-provider quota config storage (#605). Global per-provider (NOT per-host):
+// the #597 single-poller election means exactly one orchestrator polls each
+// provider fleet-wide, and the dashboard widget is global — so enable/interval/
+// show-in-widget are one decision per provider, keyed by provider id alone.
+//
+// Backed by the existing `config` table (history + `config.changed` SSE come for
+// free). Validation/clamping is the SDK's shared normalizer so the relay write
+// path and the orchestrator read path agree exactly. Separate from the per-host
+// provider *spawn* config (provider-config-store.ts) by design — different scope,
+// different cardinality.
+import { ValidationError } from "./db";
+import { getConfig, listConfig, setConfig } from "./config-store";
+import { emitConfigChanged } from "./sse";
+import {
+  DEFAULT_PROVIDER_QUOTA_CONFIG,
+  normalizeProviderQuotaConfig,
+} from "@humwick/sdk/provider-quota";
+import { SPAWN_PROVIDERS, type ProviderQuotaConfig, type ProviderQuotaConfigMap, type SpawnProvider } from "@humwick/sdk";
+
+export const PROVIDER_QUOTA_CONFIG_NAMESPACE = "provider-quota-config";
+
+export const VALID_QUOTA_CONFIG_PROVIDERS = SPAWN_PROVIDERS;
+
+function assertValidProvider(provider: string): SpawnProvider {
+  if (!(SPAWN_PROVIDERS as readonly string[]).includes(provider)) {
+    throw new ValidationError(`provider must be one of: ${SPAWN_PROVIDERS.join(", ")}`);
+  }
+  return provider as SpawnProvider;
+}
+
+/** Resolved per-provider quota config, falling back to the defaults when unset. */
+export function getProviderQuotaConfig(provider: string): ProviderQuotaConfig {
+  const clean = assertValidProvider(provider);
+  const entry = getConfig<ProviderQuotaConfig>(PROVIDER_QUOTA_CONFIG_NAMESPACE, clean);
+  return entry ? normalizeProviderQuotaConfig(entry.value) : { ...DEFAULT_PROVIDER_QUOTA_CONFIG };
+}
+
+/** Resolved config for every known provider — the orchestrator + widget read shape. */
+export function listProviderQuotaConfigs(): ProviderQuotaConfigMap {
+  return Object.fromEntries(
+    SPAWN_PROVIDERS.map((provider) => [provider, getProviderQuotaConfig(provider)]),
+  ) as ProviderQuotaConfigMap;
+}
+
+/**
+ * Persist a provider's quota config. The incoming value is normalized (interval
+ * clamped to 5m–15m, unset fields defaulted), so a partial body still validates.
+ * Emits `config.changed` so the orchestrator + dashboard pick it up live.
+ */
+export function setProviderQuotaConfig(
+  provider: string,
+  value: unknown,
+  opts: { updatedBy?: string } = {},
+): ProviderQuotaConfig {
+  const clean = assertValidProvider(provider);
+  const normalized = normalizeProviderQuotaConfig(value);
+  const entry = setConfig(PROVIDER_QUOTA_CONFIG_NAMESPACE, clean, normalized, opts.updatedBy);
+  emitConfigChanged(entry.namespace, entry.key, entry.version);
+  return normalized;
+}