@opengeni/worker-bundle 2.2.0 → 2.2.1-canary.36919050519001

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

@@ -0,0 +1,279 @@
+import { Context } from "@temporalio/activity";
+import {
+  environmentsEncryptionKeyBytes,
+  resolveFirstPartyDelegationSecret,
+  type Settings,
+} from "@opengeni/config";
+import { BROWSER_STATE_ARTIFACT_CONTENT_TYPE } from "@opengeni/contracts";
+import {
+  browserDeadlineCheckpoint,
+  clearSuspendedBrowserSessionController,
+  commitBrowserSessionSuspension,
+  dispatchBrowserSessionOperation,
+  failBrowserSessionSuspension,
+  listBrowserDeadlineCheckpoints,
+  readLease,
+  releaseLeaseHolder,
+  withRlsContext,
+  type BrowserDeadlineCheckpointTarget,
+} from "@opengeni/db";
+import { deriveBrowserControllerAdminToken } from "@opengeni/interaction/browser-controller-authority";
+import {
+  browserStateArtifactAad,
+  browserStateManifestDigest,
+  browserStateObjectKey,
+  deriveBrowserStateDataKey,
+  wrapBrowserStateDataKey,
+} from "@opengeni/interaction/browser-state-authority";
+import {
+  BrowserControlClient,
+  BrowserControlRequestError,
+  createSandboxClientForBackend,
+  deserializeSandboxSessionStateEnvelope,
+  resumeExactSandboxSession,
+  type BrowserControlPlacementSession,
+} from "@opengeni/runtime";
+import type { ControlActivityServices } from "./types";
+
+const UPLOAD_CLEANUP_GRACE_MS = 24 * 60 * 60_000;
+
+function heartbeat(): void {
+  try {
+    Context.current().heartbeat();
+  } catch {
+    // Direct embedded calls have no Temporal context. In-flight controller
+    // operations still settle under their exact durable database claim.
+  }
+}
+
+async function withActivityHeartbeat<T>(run: () => Promise<T>): Promise<T> {
+  heartbeat();
+  const timer = setInterval(heartbeat, 5_000);
+  try {
+    return await run();
+  } finally {
+    clearInterval(timer);
+  }
+}
+
+type CheckpointController = Pick<BrowserControlClient, "captureState" | "endSession">;
+type CheckpointPlacement = {
+  target: BrowserDeadlineCheckpointTarget;
+  lease: NonNullable<Awaited<ReturnType<typeof readLease>>>;
+  settings: Settings;
+  controllerRoot: string;
+};
+
+async function resumeCheckpointController({
+  target,
+  lease,
+  settings,
+  controllerRoot,
+}: CheckpointPlacement): Promise<CheckpointController> {
+  // This edge cannot create a box or route through a user's current machine.
+  const provider = createSandboxClientForBackend("modal", settings) as Parameters<
+    typeof deserializeSandboxSessionStateEnvelope
+  >[0];
+  const envelope = lease.resumeState as { sessionState?: unknown };
+  const state = await deserializeSandboxSessionStateEnvelope(
+    provider,
+    envelope.sessionState ?? lease.resumeState,
+    target.instanceId,
+  );
+  const resumed = await resumeExactSandboxSession(provider, "modal", state, target.instanceId);
+  return new BrowserControlClient(resumed.session as BrowserControlPlacementSession, {
+    adminToken: deriveBrowserControllerAdminToken({
+      rootSecret: controllerRoot,
+      accountId: target.accountId,
+      workspaceId: target.workspaceId,
+      placement: { kind: "sandbox_group", sandboxGroupId: target.sandboxGroupId },
+      placementInstanceId: target.instanceId,
+    }),
+  });
+}
+
+export function createBrowserDeadlineCheckpointActivities(
+  services: () => Promise<ControlActivityServices>,
+  connectController: (
+    placement: CheckpointPlacement,
+  ) => Promise<CheckpointController> = resumeCheckpointController,
+) {
+  return {
+    async listDueBrowserCheckpoints() {
+      return await withActivityHeartbeat(async () => {
+        const { db, settings, objectStorage } = await services();
+        if (
+          !settings.sandboxOwnershipEnabled ||
+          !objectStorage ||
+          !resolveFirstPartyDelegationSecret(settings)
+        )
+          return [];
+        const root = environmentsEncryptionKeyBytes(settings);
+        if (!root) return [];
+        root.fill(0);
+        return await listBrowserDeadlineCheckpoints(db);
+      });
+    },
+    async checkpointBrowserBeforeDeadline(target: BrowserDeadlineCheckpointTarget) {
+      return await withActivityHeartbeat(async () => {
+        const { db, settings, objectStorage } = await services();
+        const rootKey = environmentsEncryptionKeyBytes(settings);
+        const controllerRoot = resolveFirstPartyDelegationSecret(settings);
+        if (!rootKey || !objectStorage || !controllerRoot) {
+          rootKey?.fill(0);
+          throw new Error("browser deadline checkpoint storage or encryption is unavailable");
+        }
+        let dataKey: Buffer | null = null;
+        let aad: Buffer | null = null;
+        let timer: ReturnType<typeof setInterval> | null = null;
+        try {
+          const claim = await browserDeadlineCheckpoint(db, target, { prepare: true, touch: true });
+          if (!claim) return { status: "skipped" as const };
+          let pulseRunning = false;
+          let authorityLost = false;
+          const pulse = async () => {
+            if (pulseRunning) return;
+            pulseRunning = true;
+            try {
+              if (!(await browserDeadlineCheckpoint(db, target, { touch: true })))
+                authorityLost = true;
+            } finally {
+              pulseRunning = false;
+            }
+          };
+          timer = setInterval(() => {
+            void pulse().catch(() => undefined);
+          }, 5_000);
+          const lease = await readLease(db, target.workspaceId, target.sandboxGroupId);
+          if (
+            !lease ||
+            lease.instanceId !== target.instanceId ||
+            lease.leaseEpoch !== target.leaseEpoch ||
+            !lease.resumeState
+          ) {
+            throw new Error("browser deadline checkpoint placement changed");
+          }
+          const placement = {
+            kind: "sandbox_group" as const,
+            sandboxGroupId: target.sandboxGroupId,
+          };
+          const client = await connectController({ target, lease, settings, controllerRoot });
+          if (authorityLost || !(await browserDeadlineCheckpoint(db, target, { touch: true }))) {
+            throw new Error("browser deadline checkpoint authority changed");
+          }
+          if (claim.state !== "completed") {
+            const scope = { ...target, operationId: claim.operationId };
+            const objectKey = browserStateObjectKey(target.workspaceId, claim.operationId);
+            dataKey = deriveBrowserStateDataKey(rootKey, { ...scope, objectKey });
+            aad = browserStateArtifactAad({ ...scope, objectKey });
+            await dispatchBrowserSessionOperation(db, {
+              ...scope,
+              deadlineTarget: target,
+              stateUpload: {
+                objectKey,
+                cleanupAfter: new Date(Date.now() + UPLOAD_CLEANUP_GRACE_MS),
+              },
+            });
+            const signed = await objectStorage.createPutUrl({
+              key: objectKey,
+              contentType: BROWSER_STATE_ARTIFACT_CONTENT_TYPE,
+              audience: "sandbox",
+            });
+            const receipt = await client
+              .captureState({
+                ...scope,
+                objectKey,
+                afterCapture: "stop",
+                dataKey,
+                aad,
+                upload: {
+                  url: signed.url,
+                  requiredHeaders: signed.requiredHeaders,
+                  expiresAt: signed.expiresAt.toISOString(),
+                },
+              })
+              .catch(async (error: unknown) => {
+                if (
+                  error instanceof BrowserControlRequestError &&
+                  (error.error.code === "outcome_unknown" || !error.error.retryable)
+                ) {
+                  await failBrowserSessionSuspension(db, { ...scope, error: error.error });
+                }
+                throw error;
+              });
+            if (authorityLost) throw new Error("browser deadline checkpoint authority changed");
+            const portable = receipt.manifest.profileCrypto !== "platform_bound";
+            await commitBrowserSessionSuspension(db, {
+              ...scope,
+              deadlineTarget: target,
+              artifact: {
+                kind: "chromium_profile",
+                format: receipt.format,
+                objectKey,
+                artifactDigest: receipt.artifactDigest,
+                contentDigest: receipt.contentDigest,
+                manifestDigest: browserStateManifestDigest(receipt.manifest),
+                sizeBytes: receipt.sizeBytes,
+                encryptedDataKey: wrapBrowserStateDataKey(rootKey, dataKey, {
+                  ...scope,
+                  objectKey,
+                  artifactDigest: receipt.artifactDigest,
+                  contentDigest: receipt.contentDigest,
+                }),
+                materialization: {
+                  portability: portable ? "portable" : "placement_bound",
+                  reason: portable
+                    ? null
+                    : "Profile encryption depends on the source operating-system credential store.",
+                  platform: receipt.manifest.platform,
+                  architecture: receipt.manifest.architecture,
+                  engine: receipt.manifest.engine,
+                  engineVersion: receipt.manifest.engineVersion,
+                  driverId: receipt.manifest.driverId,
+                  driverSchemaVersion: receipt.manifest.driverSchemaVersion,
+                  profileCrypto: receipt.manifest.profileCrypto,
+                  providerId: null,
+                  placement: portable ? null : placement,
+                },
+              },
+            });
+          }
+          // Only remove the local profile after the encrypted artifact and its
+          // authority committed. A crash resumes this cleanup, never capture.
+          await client.endSession(target, { removeState: true }).catch((error: unknown) => {
+            if (!(error instanceof BrowserControlRequestError && error.status === 404)) throw error;
+          });
+          await withRlsContext(
+            db,
+            target,
+            async (tx) => {
+              if ((await browserDeadlineCheckpoint(tx, target))?.state !== "completed") {
+                throw new Error("browser deadline checkpoint cleanup authority changed");
+              }
+              await clearSuspendedBrowserSessionController(tx, {
+                ...target,
+                expectedControllerGeneration: target.controllerGeneration,
+              });
+              // One transaction prevents a human resume from acquiring a new
+              // same-browser holder between clearing and releasing the old one.
+              await releaseLeaseHolder(tx, {
+                ...target,
+                kind: "interaction",
+                holderId: `browser-session:${target.browserSessionId}`,
+                idleGraceMs: settings.sandboxIdleGraceMs,
+              });
+            },
+            undefined,
+            "none",
+          );
+          return { status: "suspended" as const };
+        } finally {
+          if (timer) clearInterval(timer);
+          dataKey?.fill(0);
+          aad?.fill(0);
+          rootKey.fill(0);
+        }
+      });
+    },
+  };
+}

package/src/activities/capabilities.ts

@@ -40,6 +40,8 @@ import {
   listWorkspaceProviderCustomModels,
   getWorkspaceProviderCustomModelForExecution,
   loadWorkspaceProviderApiKey,
+  loadClaudeSubscriptionUsageCredential,
+  assertModelConnectionAllowsTurn,
   type Database,
   type SessionMcpServerForRun,
 } from "@opengeni/db";
@@ -303,12 +305,30 @@ export async function settingsWithOrganizationProviderCredentials(
     if (kind === "claude_subscription" && !settings.claudeSubscriptionEnabled) continue;
     const models = await buildModels(kind, claudeProviderId(kind) + "/");
     result = withClaudeConnectionCatalog(result, { [kind]: { models } });
-    const credential = await loadOrganizationModelProviderApiKey(db, settings, {
-      accountId,
-      workspaceId,
-      providerKind: kind,
-    });
-    if (credential) result = withClaudeConnectionCredential(result, kind, credential);
+    const binding =
+      kind === "claude_subscription"
+        ? await loadClaudeSubscriptionUsageCredential(db, settings, {
+            accountId,
+            workspaceId,
+            scope: "organization",
+          })
+        : null;
+    const credential =
+      kind === "claude_subscription"
+        ? binding?.serializedCredential
+        : await loadOrganizationModelProviderApiKey(db, settings, {
+            accountId,
+            workspaceId,
+            providerKind: kind,
+          });
+    if (credential)
+      result = withClaudeConnectionCredential(
+        result,
+        kind,
+        credential,
+        "organization",
+        binding ?? undefined,
+      );
     const workspaceModels = await listWorkspaceProviderCustomModels(db, {
       accountId,
       workspaceId,
@@ -333,15 +353,33 @@ export async function settingsWithOrganizationProviderCredentials(
       { [kind]: { models: workspaceModels } },
       "workspace",
     );
-    const workspaceCredential = await loadWorkspaceProviderApiKey(
-      db,
-      settings,
-      workspaceId,
-      kind,
-      workspaceModelId,
-    );
+    const workspaceBinding =
+      kind === "claude_subscription"
+        ? await loadClaudeSubscriptionUsageCredential(db, settings, {
+            accountId,
+            workspaceId,
+            scope: "workspace",
+          })
+        : null;
+    if (workspaceBinding && workspaceModelId)
+      await assertModelConnectionAllowsTurn(db, {
+        workspaceId,
+        subjectId: "worker:model-access",
+        modelId: workspaceModelId,
+        workspaceProviderConnectionId: workspaceBinding.connectionId,
+      });
+    const workspaceCredential =
+      kind === "claude_subscription"
+        ? workspaceBinding?.serializedCredential
+        : await loadWorkspaceProviderApiKey(db, settings, workspaceId, kind, workspaceModelId);
     if (workspaceCredential)
-      result = withClaudeConnectionCredential(result, kind, workspaceCredential, "workspace");
+      result = withClaudeConnectionCredential(
+        result,
+        kind,
+        workspaceCredential,
+        "workspace",
+        workspaceBinding ?? undefined,
+      );
   }
   return result;
 }

package/src/activities/goals.ts

@@ -1,6 +1,7 @@
 import {
   allowedFirstPartyMcpToolsForSession,
   configuredStaticUsageLimits,
+  isModelAvailableForNewSelection,
   policyProviderIdForModel,
   resolveModelProvider,
   resolveTurnExecutionPolicyV1,
@@ -19,14 +20,10 @@ import {
 import { isCodexBilledModel } from "@opengeni/codex";
 import {
   enqueueSessionWorkflowWakeIfRunnable,
-  getBillingBalance,
   getWorkspaceModelPolicy,
   getSessionGoal,
-  isCodexBilledTurn,
   materializeGoalContinuation,
   requireSession,
-  sumUsageQuantity,
-  type Database,
 } from "@opengeni/db";
 import type {
   ControlActivityServices,
@@ -38,6 +35,7 @@ import {
   resolveCatalogSettings,
   resolveWorkspaceCatalogSettings,
 } from "@opengeni/core";
+import { agentRunAdmissionDenial } from "./agent-run-admission";
 
 export function createGoalActivities(services: () => Promise<ControlActivityServices>) {
   async function enqueueGoalRetryWake(input: MaybeContinueGoalInput): Promise<void> {
@@ -65,7 +63,6 @@ export function createGoalActivities(services: () => Promise<ControlActivityServ
     if (!existingGoal || existingGoal.status !== "active") {
       return { action: "none" };
     }
-    let settings = (await resolveCatalogSettings(db, catalogSourceSettings)).settings;
     // Loaded before the budget check so the codex-billed predicate and the
     // synthesized turn use the SAME effective policy. An explicit per-turn
     // model can differ from the persisted session default; follow-up goal work
@@ -74,6 +71,13 @@ export function createGoalActivities(services: () => Promise<ControlActivityServ
     // Kept below the goal-less fast path so a non-goal session still skips the
     // reads entirely.
     const session = await requireSession(db, input.workspaceId, input.sessionId);
+    // Terminal sessions retain their goal for human recovery, but cannot
+    // continue. Do not validate an obsolete model before the locked guard gets
+    // the chance to reject that work; otherwise a deterministic error retries.
+    if (session.status === "failed" || session.status === "cancelled") {
+      return { action: "none" };
+    }
+    let settings = (await resolveCatalogSettings(db, catalogSourceSettings)).settings;
     const inheritedContinuationModel = session.model;
     let continuationModel = inheritedContinuationModel;
     const continuationReasoningEffort = session.reasoningEffort;
@@ -109,39 +113,17 @@ export function createGoalActivities(services: () => Promise<ControlActivityServ
     ) {
       modelPolicyBlocked = `session is locked to Codex remote compaction v2; model "${continuationModel}" is not a Codex subscription model`;
     }
-    // A codex-model goal continuation is paid by the user's ChatGPT/Codex plan,
-    // so it must not be budget-paused for zero OpenGeni credits. This file uses
-    // BASE settings (no codex overlay); the predicate does its own credential read.
-    const isCodexRun = await isCodexBilledTurn({
-      db,
-      settings,
-      workspaceId: input.workspaceId,
-      model: continuationModel,
-    });
-    const fundedWithoutCredits = goalContinuationFundedWithoutCredits(
-      settings,
-      continuationModel,
-      isCodexRun,
-    );
-    // Budget exhaustion pauses the goal visibly instead of failing the
-    // session. Computed up front and applied inside the locked decision so a
-    // limits pause never consumes continuation budget.
-    const budgetBlocked = await goalRunBudgetBlocked(
-      settings,
-      db,
-      input.accountId,
-      input.workspaceId,
-      fundedWithoutCredits,
-    );
-    const turnExecutionPolicy = resolveTurnExecutionPolicyV1(settings, {
-      modelId: continuationModel,
-      requestedModelId: null,
-      modelSource: "continuation",
-      reasoningEffort: continuationReasoningEffort,
-      reasoningSource: "continuation",
-      latencyMode: continuationLatencyMode,
-      latencyModeSource: "continuation",
-    });
+    const turnExecutionPolicy = modelPolicyBlocked
+      ? undefined
+      : resolveTurnExecutionPolicyV1(settings, {
+          modelId: continuationModel,
+          requestedModelId: null,
+          modelSource: "continuation",
+          reasoningEffort: continuationReasoningEffort,
+          reasoningSource: "continuation",
+          latencyMode: continuationLatencyMode,
+          latencyModeSource: "continuation",
+        });
     const decision = await materializeGoalContinuation(db, {
       accountId: input.accountId,
       workspaceId: input.workspaceId,
@@ -157,12 +139,30 @@ export function createGoalActivities(services: () => Promise<ControlActivityServ
       // A model-policy block takes precedence: it is deterministic (a budget
       // pause can clear on its own; a policy pause needs a model/policy change)
       // and rides the same visible-pause channel.
-      budgetBlocked: modelPolicyBlocked ?? budgetBlocked,
+      admission: async (tx, causalTurn) => {
+        const budgetBlocked = modelPolicyBlocked
+          ? null
+          : await goalRunBudgetBlocked(
+              { ...service, settings, db: tx },
+              {
+                accountId: input.accountId,
+                workspaceId: input.workspaceId,
+                model: continuationModel,
+                initiatingHumanSubjectId: causalTurn?.initiatingHumanSubjectId ?? null,
+              },
+            );
+        return {
+          budgetBlocked: modelPolicyBlocked ?? budgetBlocked?.message ?? null,
+          budgetPausedReason: modelPolicyBlocked
+            ? "limits"
+            : (budgetBlocked?.pausedReason ?? "limits"),
+        };
+      },
       policy: {
         model: continuationModel,
         reasoningEffort: continuationReasoningEffort,
         latencyMode: continuationLatencyMode,
-        turnExecutionPolicy,
+        ...(turnExecutionPolicy ? { turnExecutionPolicy } : {}),
         tools: withFirstPartyTools(settings, session.tools),
         sandboxBackend: session.sandboxBackend,
       },
@@ -215,18 +215,21 @@ export function goalContinuationModelDecision(input: {
       providerId: policyProviderIdForModel(catalogSettings, modelId),
       modelId,
     }).allowed;
-  if (
-    resolveModelProvider(catalogSettings, input.inheritedModel) &&
-    !policyBlocks(input.inheritedModel)
-  ) {
-    return { model: input.inheritedModel, blocked: null };
-  }
   if (!resolveModelProvider(catalogSettings, input.inheritedModel)) {
     return {
       model: input.inheritedModel,
       blocked: `model "${input.inheritedModel}" is no longer in the deployment or workspace catalog; choose an available model before resuming the goal`,
     };
   }
+  if (!isModelAvailableForNewSelection(catalogSettings, input.inheritedModel)) {
+    return {
+      model: input.inheritedModel,
+      blocked: `model "${input.inheritedModel}" is retired from new selection; choose an available model before resuming the goal`,
+    };
+  }
+  if (!policyBlocks(input.inheritedModel)) {
+    return { model: input.inheritedModel, blocked: null };
+  }
   return {
     model: input.inheritedModel,
     blocked: `workspace model policy blocks model "${input.inheritedModel}"; pick an allowed model or change the workspace model policy`,
@@ -307,6 +310,8 @@ export function goalContinuationPrompt(
     "- For document report deliverables (a document the user asked for, or a large report meant to be kept or shared), follow the Documents Skill: create the durable native document first, inspect its relevant final head after the last edit, and provide the returned artifact reference. Declare report requirements through the available goal tools before authoring and satisfy every persisted report requirement with verified artifact delivery evidence before completion. Sandbox paths and raw file IDs do not prove report delivery. If artifact tooling or access is unavailable, keep that deliverable incomplete and state the blocker; never invent proof or silently substitute a local report. Ordinary chat answers, short progress updates, source-code links, and explicitly requested local-file work remain outside this report contract.",
     "",
     "Do not rely on intent, partial progress, memory of earlier work, or a plausible final answer as proof of completion. Call opengeni__goal_complete with concrete evidence only when the full objective is actually achieved and no required work remains.",
+    "Goal evidence is a short proof for the ledger, not the deliverable. After goal_complete succeeds, finish this same turn with the requested user-facing answer, or a concise summary and retained artifact link. Goal completion stops future automatic continuations; it does not send the answer or end this turn. Never compress a report into evidence or omit the final reply.",
+    "Goal progress notes are short human-readable milestone statuses, not raw transcripts or continuation instructions. Keep normal spaces and summarize detail instead of squeezing words into a ledger field. The text and successCriteria fields each allow 8192 UTF-8 bytes, progressNote allows 8192 UTF-8 bytes, rationale allows 2048 UTF-8 bytes, and evidence allows 8192 characters.",
     "",
     ...waitingGuidance,
     ...childNoticeGuidance,
@@ -336,55 +341,22 @@ export function withFirstPartyTools(settings: Settings, tools: ToolRef[]): ToolR
 }
 
 /**
- * Non-throwing variant of the scheduled-run admission check: returns a human
- * readable reason when balance or monthly caps block another agent run.
+ * Goals share scheduled admission and pause visibly without synthesizing work.
  */
-async function goalRunBudgetBlocked(
-  settings: Settings,
-  db: Database,
-  accountId: string,
-  workspaceId: string,
-  fundedWithoutCredits: boolean,
-): Promise<string | null> {
-  // Free, subscription, and workspace-funded continuations skip OpenGeni's
-  // credit-balance gate and monthly model-cost cap. The agent-run COUNT cap
-  // below is a volume quota (not a credit/cost gate) and remains enforced.
-  if (
-    !fundedWithoutCredits &&
-    (settings.billingMode === "stripe" || settings.usageLimitsMode === "managed")
-  ) {
-    const balance = await getBillingBalance(db, accountId);
-    if (balance.balanceMicros <= 0) {
-      return "insufficient OpenGeni credits";
-    }
-  }
-  if (settings.usageLimitsMode === "static" || settings.usageLimitsMode === "managed") {
-    const limits = configuredStaticUsageLimits(settings);
-    if (!fundedWithoutCredits && limits.maxMonthlyCostMicrosPerAccount) {
-      const used = await sumUsageQuantity(db, {
-        accountId,
-        eventType: "model.cost",
-        since: startOfUtcMonth(),
-      });
-      if (used >= limits.maxMonthlyCostMicrosPerAccount) {
-        return `monthly model cost limit reached (${limits.maxMonthlyCostMicrosPerAccount} micros)`;
-      }
-    }
-    if (limits.maxMonthlyAgentRunsPerWorkspace) {
-      const used = await sumUsageQuantity(db, {
-        workspaceId,
-        eventType: "agent_run.created",
-        since: startOfUtcMonth(),
-      });
-      if (used + 1 > limits.maxMonthlyAgentRunsPerWorkspace) {
-        return `monthly agent run limit reached (${limits.maxMonthlyAgentRunsPerWorkspace})`;
-      }
-    }
+export async function goalRunBudgetBlocked(
+  services: Parameters<typeof agentRunAdmissionDenial>[0],
+  input: Omit<Parameters<typeof agentRunAdmissionDenial>[1], "requestedAgentRuns">,
+): Promise<{ pausedReason: "limits" | "allowance"; message: string } | null> {
+  const denial = await agentRunAdmissionDenial(services, { ...input, requestedAgentRuns: 1 });
+  if (denial === null) return null;
+  if (denial === "allowance_exhausted") {
+    return { pausedReason: "allowance", message: "OpenGeni usage allowance exhausted" };
   }
-  return null;
-}
-
-function startOfUtcMonth(): Date {
-  const now = new Date();
-  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+  const limits = configuredStaticUsageLimits(services.settings);
+  const messages = {
+    insufficient_credits: "insufficient OpenGeni credits",
+    monthly_model_cost_limit: `monthly model cost limit reached (${limits.maxMonthlyCostMicrosPerAccount} micros)`,
+    monthly_agent_run_limit: `monthly agent run limit reached (${limits.maxMonthlyAgentRunsPerWorkspace})`,
+  };
+  return { pausedReason: "limits", message: messages[denial] };
 }

package/src/activities/knowledge-indexing.ts

@@ -4,8 +4,10 @@ import {
   applyCreditDebitAfterUse,
   appendKnowledgeIndexChunks,
   claimKnowledgeIndexJobs,
+  checkWorkspaceAllowance,
   completeKnowledgeIndexJob,
   continueKnowledgeIndexJob,
+  creditDebitAttributionMetadata,
   deferKnowledgeIndexJob,
   freezeKnowledgeIndexBillingMode,
   getBillingBalance,
@@ -198,6 +200,16 @@ export function createKnowledgeIndexingActivities(
                 return;
               }
               const paid = frozenPolicy.mode === "credits";
+              if (paid && claim.billingAttribution.kind === "unknown") {
+                // Unknown legacy/source-preparation causality is not service.
+                // Keep the checkpoint without making an uncountable paid call.
+                observability.warn("Paid Knowledge indexing awaits initiating attribution", {
+                  errorCode: "knowledge_index_attribution_unavailable",
+                });
+                await deferKnowledgeIndexJob(lockedDb, claim);
+                result.deferred++;
+                return;
+              }
               if (paid && current.nextIndex === 0) {
                 const balance = await getBillingBalance(lockedDb, claim.accountId);
                 if (balance.balanceMicros <= 0) {
@@ -206,6 +218,22 @@ export function createKnowledgeIndexingActivities(
                   return;
                 }
               }
+              if (paid) {
+                const refusal = await checkWorkspaceAllowance(lockedDb, {
+                  accountId: claim.accountId,
+                  workspaceId: current.billingWorkspaceId,
+                  subjectId:
+                    claim.billingAttribution.kind === "turn" ||
+                    claim.billingAttribution.kind === "human"
+                      ? claim.billingAttribution.initiatingHumanSubjectId
+                      : null,
+                });
+                if (refusal) {
+                  await deferKnowledgeIndexJob(lockedDb, claim);
+                  result.deferred++;
+                  return;
+                }
+              }
               if (settings.usageLimitsMode === "static" || settings.usageLimitsMode === "managed") {
                 const limit =
                   configuredStaticUsageLimits(settings).maxDocumentIndexedChunksPerWorkspace;
@@ -309,6 +337,7 @@ export function createKnowledgeIndexingActivities(
                     sourceId: claim.revisionId,
                     idempotencyKey: `knowledge.embedding:${claim.revisionId}:${claim.generation}:${current.nextIndex}`,
                     metadata: {
+                      ...creditDebitAttributionMetadata(claim.billingAttribution),
                       model: claim.model,
                       bytes,
                       chunks: chunks.length,