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

package/dist/activities/sandbox-lease.d.ts

@@ -1,8 +1,8 @@
-import type { ProviderCommandPersistence } from "@opengeni/runtime";
+import type { ProviderCommandPersistence, ProviderCommandSession } from "@opengeni/runtime";
 import { type OpStatus } from "@opengeni/agent-proto";
 import { listLiveModalSandboxLeaseAttributions, readLease, type ReapDrainable, type RetainedProcessProviderProof, type SandboxRetainedProcess, type LeaseSnapshot } from "@opengeni/db";
 import { type ConnectedMachineBackgroundCommandClaim, type ConnectedMachineBackgroundCommandProof } from "@opengeni/db/session-background-commands";
-import { type VerifiedHostWorkspaceArchive, createSandboxClientForBackend, inspectModalSandboxLifecycle, resolveModalCheckpointProviderBindingForSession, terminateModalSandboxById, type ModalOrphanSweepTermination, type ModalCheckpointProviderBinding, type ProviderWorkspaceCapturePolicy, type WorkspaceArchiveDescriptor, type ControlRpc } from "@opengeni/runtime/sandbox";
+import { type VerifiedHostWorkspaceArchive, createSandboxClientForBackend, inspectModalSandboxLifecycle, OpStreamExecClient, findModalProviderCreateReceipt, resolveModalCheckpointProviderBindingForSession, terminateModalSandboxById, type ModalOrphanSweepTermination, type ModalCheckpointProviderBinding, type ProviderWorkspaceCapturePolicy, type WorkspaceArchiveDescriptor, type ControlRpc } from "@opengeni/runtime/sandbox";
 import { type SandboxDrainActivityInput, type SandboxLeaseSweepMaintenanceInput } from "../sandbox-reaper-contract.js";
 import type { ControlActivityServices as ActivityServices } from "./types.js";
 import { type RetainedProcessReconciliationOutcome } from "../observability-metrics.js";
@@ -20,8 +20,7 @@ export type ReapSandboxLeasesResult = {
     skipped: number;
     /** Warm viewer-only leases that accrued warm-seconds this tick (P2.1). */
     metered: number;
-    /** Viewer-only boxes force-drained because their workspace is over a limit
-     *  (0 balance / over the warm cap) — turn-held boxes are never drained (P2.1). */
+    /** Holderless boxes accelerated to draining by the optional warm cap. */
     forceDrained: number;
     /** Provider-side Modal orphan sandboxes terminated by the defensive sweep. */
     modalOrphansTerminated: number;
@@ -60,7 +59,7 @@ export type DrainCaptureDisposition = "capture_required" | "archive_published";
  *  Test seams may return the legacy boolean shorthand. Production returns the
  *  typed outcome so the cold commit can distinguish a clean stop from definitive
  *  provider disappearance before capture. */
-export type TerminateBoxFn = (settings: ActivityServices["settings"], lease: NonNullable<Awaited<ReturnType<typeof readLease>>>, observability: ActivityServices["observability"], persistArchive: PersistArchiveFn, providerCaptureRequestId?: string, captureDisposition?: DrainCaptureDisposition, capturePolicy?: ProviderWorkspaceCapturePolicy | null, diskBackedArchives?: boolean, releaseFailedCapture?: () => Promise<void>) => Promise<boolean | ProviderTerminationOutcome>;
+export type TerminateBoxFn = (settings: ActivityServices["settings"], lease: NonNullable<Awaited<ReturnType<typeof readLease>>>, observability: ActivityServices["observability"], persistArchive: PersistArchiveFn, providerCaptureRequestId?: string, captureDisposition?: DrainCaptureDisposition, capturePolicy?: ProviderWorkspaceCapturePolicy | null, diskBackedArchives?: boolean, releaseFailedCapture?: () => Promise<void>, workspaceId?: string, beforeProviderStop?: () => Promise<void>) => Promise<boolean | ProviderTerminationOutcome>;
 export type SweepModalOrphansFn = (settings: ActivityServices["settings"], db: ActivityServices["db"], observability: ActivityServices["observability"]) => Promise<number>;
 export type InspectOpenSandboxKubernetesInventoryFn = (input: {
     namespace: string;
@@ -72,6 +71,8 @@ export type SandboxLeaseActivityOptions = {
     /** Override the provider-side Modal orphan sweep (tests spy this; defaults to
      *  Modal list+tag comparison when Modal is configured). */
     sweepModalOrphans?: SweepModalOrphansFn;
+    /** Only provider discovery is injected; durable recovery remains real. */
+    findModalProviderCreateReceipt?: typeof findModalProviderCreateReceipt;
     /** Override the read-only bounded OpenSandbox Kubernetes projection. */
     inspectOpenSandboxKubernetesInventory?: InspectOpenSandboxKubernetesInventoryFn;
     /** Override only the read-only provider process probe. The canonical DB
@@ -94,13 +95,29 @@ export type RetainedProcessProbeResult = {
 } | {
     status: "deferred";
     reason: "identity_mismatch" | "resume_state_missing" | "backend_unsupported" | "provider_running" | "provider_unknown" | "provider_timeout" | "provider_error" | "provider_binding_missing" | "provider_binding_mismatch" | "process_observation_unavailable";
+    /** A running command whose last read still returned a large backlog. */
+    outputBacklog?: boolean;
+};
+export type RetainedProcessProbeFn = (settings: ActivityServices["settings"], lease: LeaseSnapshot, process: SandboxRetainedProcess, mode?: "observe" | "cancel", captureOutput?: (result: unknown, chunkId: string, stream?: "stdout" | "stderr", streamFidelity?: "separate" | "merged") => Promise<void>, providerPersistence?: ProviderCommandPersistence, drainBudget?: RetainedProcessDrainBudget) => Promise<RetainedProcessProbeResult>;
+/** Shared wall-clock bound on output draining within one reconciliation sweep. */
+export type RetainedProcessDrainBudget = {
+    until: number;
 };
-export type RetainedProcessProbeFn = (settings: ActivityServices["settings"], lease: LeaseSnapshot, process: SandboxRetainedProcess, mode?: "observe" | "cancel", captureOutput?: (result: unknown, chunkId: string, stream?: "stdout" | "stderr", streamFidelity?: "separate" | "merged") => Promise<void>, providerPersistence?: ProviderCommandPersistence) => Promise<RetainedProcessProbeResult>;
 export type HistoricalModalSandboxLifecycleProbeFn = typeof inspectModalSandboxLifecycle;
 export type DrainableProviderProbeFn = (settings: ActivityServices["settings"], lease: LeaseSnapshot) => Promise<"ready" | "missing">;
 export declare const RETAINED_PROCESS_RECONCILIATION_LIMIT = 20;
 export declare const RETAINED_PROCESS_RECONCILIATION_CLAIM_TTL_MS: number;
 export declare const RETAINED_PROCESS_PROVIDER_PROBE_TIMEOUT_MS = 5000;
+/** Bounds on reading a command's output backlog: per claim, and across one
+ * reconciliation sweep so the reaper activity stays well inside its timeout.
+ * Each read returns up to one provider page per stream. */
+export declare const RETAINED_PROCESS_OUTPUT_DRAIN_MAX_READS = 8;
+export declare const RETAINED_PROCESS_OUTPUT_DRAIN_BUDGET_MS = 10000;
+export declare const RETAINED_PROCESS_OUTPUT_DRAIN_SWEEP_BUDGET_MS = 60000;
+/** A live process whose read returned at least this much output left a backlog
+ * behind it. A server or watcher that only trickles output stays on ordinary
+ * backoff; a process the provider reports exited is always read to EOF. */
+export declare const RETAINED_PROCESS_OUTPUT_BACKLOG_BYTES: number;
 export declare const RETAINED_PROCESS_BINDING_QUARANTINE_AFTER_ATTEMPTS = 5;
 export declare const RETAINED_PROCESS_BINDING_QUARANTINE_RETRY_MS: number;
 export declare const CONNECTED_COMMAND_RECONCILIATION_LIMIT = 20;
@@ -154,22 +171,43 @@ export declare function createSandboxLeaseActivities(services: () => Promise<Act
  * adoption. A successor enrollment connection is intentionally irrelevant: no
  * query or cancellation is ever rebound to it. */
 export declare function reconcileConnectedMachineBackgroundCommands(db: ActivityServices["db"], settings: ActivityServices["settings"], observability: ActivityServices["observability"], bus: ActivityServices["bus"], controlRpcOverride?: ControlRpc): Promise<void>;
+export declare function replayConnectedCommandOutput(client: Pick<OpStreamExecClient, "readExisting">, opId: string, terminalKnown: boolean, capture: Parameters<OpStreamExecClient["readExisting"]>[2]): Promise<Awaited<ReturnType<OpStreamExecClient["readExisting"]>>>;
+/** Drain the durable terminal-output obligation independently of the launching
+ * attempt or model completion notice. Existing terminal rows receive no inferred
+ * receipt: they must replay and capture all retained bytes before any final ACK. */
+export declare function reconcileConnectedCommandOutputReleases(db: ActivityServices["db"], settings: ActivityServices["settings"], observability: ActivityServices["observability"], bus: ActivityServices["bus"], controlRpcOverride?: ControlRpc): Promise<void>;
 export declare function probeConnectedMachineBackgroundCommand(claim: ConnectedMachineBackgroundCommandClaim, controlRpc: ControlRpc, controlTimeoutMs: number, observedAt?: Date): Promise<ConnectedMachineBackgroundCommandProof | null>;
 export declare function connectedCommandProofFromStatus(status: OpStatus, observedAt: Date): ConnectedMachineBackgroundCommandProof | null;
 type RetainedProcessDeferralOutcome = Extract<RetainedProcessProbeResult, {
     status: "deferred";
 }>["reason"] | "settlement_failed";
-export declare function retainedProcessReconciliationDeferral(settings: Pick<ActivityServices["settings"], "sandboxLeaseReaperPeriodMs">, process: Pick<SandboxRetainedProcess, "reconcileAttempts">, outcome: RetainedProcessDeferralOutcome): {
+export declare function retainedProcessReconciliationDeferral(settings: Pick<ActivityServices["settings"], "sandboxLeaseReaperPeriodMs">, process: Pick<SandboxRetainedProcess, "reconcileAttempts">, outcome: RetainedProcessDeferralOutcome, outputBacklog?: boolean): {
     durableOutcome: string;
     metricOutcome: RetainedProcessReconciliationOutcome;
     retryAfterMs: number;
     quarantined: boolean;
 };
+type RetainedProcessProbeSession = ProviderCommandSession & {
+    acknowledgeCommandOutput?: (result: string) => Promise<void>;
+    writeStdin?: (args: {
+        sessionId: number;
+        chars: string;
+        yieldTimeMs: number;
+        maxOutputTokens: number;
+    }) => Promise<unknown>;
+};
+/** A command's exit is reported only after both output streams reach EOF, so a
+ * finished command with a large backlog looks running until it is read. While a
+ * backlog remains, keep reading within the per-claim and per-sweep budgets, so
+ * it settles in this claim instead of one page per backoff step. Every page,
+ * including `first`, is captured here. */
+export declare function drainRetainedCommandBacklog(session: RetainedProcessProbeSession, providerSessionId: number, first: unknown, capturePage: (value: unknown) => Promise<void>, budget?: RetainedProcessDrainBudget): Promise<RetainedProcessProbeResult>;
 export declare function captureRetainedProbeOutput(processId: string, result: unknown, capture: (result: unknown, chunkId: string) => Promise<void>): Promise<void>;
-export declare function probeRetainedProcessAtProvider(settings: ActivityServices["settings"], lease: LeaseSnapshot, process: SandboxRetainedProcess, mode?: "observe" | "cancel", captureOutput?: (result: unknown, chunkId: string, stream?: "stdout" | "stderr", streamFidelity?: "separate" | "merged") => Promise<void>, providerPersistence?: ProviderCommandPersistence): Promise<RetainedProcessProbeResult>;
+export declare function probeRetainedProcessAtProvider(settings: ActivityServices["settings"], lease: LeaseSnapshot, process: SandboxRetainedProcess, mode?: "observe" | "cancel", captureOutput?: (result: unknown, chunkId: string, stream?: "stdout" | "stderr", streamFidelity?: "separate" | "merged") => Promise<void>, providerPersistence?: ProviderCommandPersistence, drainBudget?: RetainedProcessDrainBudget): Promise<RetainedProcessProbeResult>;
 /** Classify only exact SDK control banners. Arbitrary output, malformed text,
  * and a running marker are observations to retry; none is physical exit proof. */
 export declare function classifyRetainedProcessPollResult(result: unknown, providerSessionId: number, source?: object): RetainedProcessProbeResult;
+export declare function reconcileModalProviderCreates(db: ActivityServices["db"], settings: ActivityServices["settings"], observability: ActivityServices["observability"], discover?: typeof findModalProviderCreateReceipt): Promise<void>;
 export declare function modalOrphanTerminationStillEligible(latest: Awaited<ReturnType<typeof listLiveModalSandboxLeaseAttributions>>, candidate: ModalOrphanSweepTermination): boolean;
 export type SandboxDrainReason = "idle" | "provider_deadline" | "operator" | "teardown_claim" | "rotation_requested";
 /** The bounded drain reason carried on `sandbox.box.terminated`: the lease's
@@ -207,4 +245,4 @@ export declare function sandboxDrainReason(lease: Pick<LeaseSnapshot, "rotationR
  * draining until its adapter can prove termination. A truly instance-less or
  * `none`-backed row is a no-op.
  */
-export declare function terminateProviderBox(settings: ActivityServices["settings"], lease: NonNullable<Awaited<ReturnType<typeof readLease>>>, observability: ActivityServices["observability"], persistArchive: PersistArchiveFn, createClientForBackend?: CreateSandboxClientForBackendFn, terminateModalById?: typeof terminateModalSandboxById, providerCaptureRequestId?: string, captureDisposition?: DrainCaptureDisposition, claimedCapturePolicy?: ProviderWorkspaceCapturePolicy | null, diskBackedArchives?: boolean, releaseFailedCapture?: () => Promise<void>): Promise<ProviderTerminationOutcome>;
+export declare function terminateProviderBox(settings: ActivityServices["settings"], lease: NonNullable<Awaited<ReturnType<typeof readLease>>>, observability: ActivityServices["observability"], persistArchive: PersistArchiveFn, createClientForBackend?: CreateSandboxClientForBackendFn, terminateModalById?: typeof terminateModalSandboxById, providerCaptureRequestId?: string, captureDisposition?: DrainCaptureDisposition, claimedCapturePolicy?: ProviderWorkspaceCapturePolicy | null, diskBackedArchives?: boolean, releaseFailedCapture?: () => Promise<void>, workspaceId?: string, beforeProviderStop?: () => Promise<void>): Promise<ProviderTerminationOutcome>;

package/dist/activities/scheduled-tasks.d.ts

@@ -1,3 +1,4 @@
+import { TurnExecutionPolicyV1 } from "@opengeni/contracts";
 import { updateSessionTitleWithEvent } from "@opengeni/db";
 import type { ControlActivityServices, DispatchScheduledTaskRunInput, DispatchScheduledTaskRunResult } from "./types.js";
 import type { Database } from "@opengeni/db";
@@ -9,43 +10,11 @@ type ScheduledTemporalActivityIdentity = {
     };
     activityId: string;
 };
+export declare function scheduledTaskRunExecutionPolicy(policy: TurnExecutionPolicyV1, input: DispatchScheduledTaskRunInput, creatorRestriction?: "developer_setup"): TurnExecutionPolicyV1;
+/** Only a creator ceiling is standing; a manual caller ceiling is per-run. */
+export declare function scheduledSessionExecutionPolicyMetadata(policy: unknown, creatorRestriction?: "developer_setup"): Record<string, unknown>;
 export declare function scheduledTaskRunProducerKey(input: DispatchScheduledTaskRunInput, suppliedActivityIdentity?: ScheduledTemporalActivityIdentity): string;
 export declare function scheduledTaskGeneratedSessionCreateIdempotencyKey(producerKey: string): string;
-/**
- * Display title for a session the scheduler generates for a task.
- *
- * A scheduled session's `initialMessage` is the task prompt, byte-identical for
- * every run. The task name is the short human-chosen label that actually
- * identifies it, so that is the title.
- *
- * The title is the task name and NOTHING else. It deliberately does not name the
- * run's fire instant, for two independent reasons:
- *
- *   - No run mode guarantees one run per session. `reusable_session` generates
- *     its session on the first fire and then reuses it forever, and even under
- *     `new_session_per_run` alert-occurrence redelivery converges several runs
- *     onto one canonical responder session. `existing_session` never generates a
- *     session at all, so the scheduler never titles one. A run-specific fact
- *     frozen into the title is therefore right for the generating run and a lie
- *     for every run that lands in the same session afterwards.
- *   - A title is one stored string shown to every viewer, while every surface
- *     that renders a run's fire instant renders it viewer-local: the rail row
- *     prints the title beside `relativeTimeLabel(session.updatedAt)`, and the
- *     Schedules run list prints `formatTimestamp(run.firedAt)`, which is
- *     `toLocaleString()`. A wall clock stored in the title therefore disagrees
- *     with the time printed next to it for every viewer outside whichever zone
- *     it was rendered in. The task's own `timeZone` is no escape: it labels the
- *     schedule rule ("Mon Wed 09:00 Europe/Oslo"), not the rendering of a run,
- *     which stays viewer-local. No stored clock can agree with a viewer-local
- *     one, so the title carries none and the instant stays on the surfaces that
- *     already render it correctly.
- *
- * Dropping the clock settles the determinism constraint outright rather than
- * working around it: the same run titled by the normal dispatch or by a later
- * recovery in a different worker process derives one string from `task.name`
- * alone, with no Intl call and so no host ICU or tzdata build to make the two
- * texts differ.
- */
 export declare function scheduledTaskSessionTitle(taskName: string): string;
 /**
  * Title a session the scheduler generated, and emit the same `session.title_set`

package/dist/activities/session-state.d.ts

@@ -1,24 +1,29 @@
-import { settleSessionAttemptInterruptions, applySessionTurnSettlement, enqueueSessionWorkflowWake, failSessionWorkBeforeAttemptClaim, requestSessionTurnRecovery, recoverSessionDispatch, reconcileSessionAttemptQuiescence, peekSessionWork as peekSessionWorkDb, settleSessionInputWait as settleSessionInputWaitDb, countQueuedTurns, getSessionAttemptActivityRef, getSessionEvent, getSessionTurnForAttempt, expireSessionInteractionIntervention as expireSessionInteractionInterventionDb, expireSessionHumanInputRequest, markSessionAttemptQuiesced, requireSession, settleSessionIdleWithParentOutbox } from "@opengeni/db";
+import { settleSessionAttemptInterruptions, applySessionTurnSettlement, enqueueSessionWorkflowWake, failSessionWorkBeforeAttemptClaim, blockSessionWorkBeforeAttemptClaim, requestSessionTurnRecovery, recoverSessionDispatch, reconcileSettledSessionAttempt, reconcileSessionAttemptQuiescence, reconcileCompletedSandboxSetup, peekSessionWork as peekSessionWorkDb, settleSessionInputWait as settleSessionInputWaitDb, countQueuedTurns, getSessionAttemptActivityRef, getSessionEvent, getSessionTurnForAttempt, getWorkspace, expireSessionInteractionIntervention as expireSessionInteractionInterventionDb, expireScheduledRunHumanWait as expireScheduledRunHumanWaitDb, expireSessionHumanInputRequest, markSessionAttemptQuiesced, requireSession, settleSessionIdleWithParentOutbox } from "@opengeni/db";
 import { publishDurableSessionEvents } from "@opengeni/events";
 import { deliverFailedChildTurnToParent, notifyParentOfChildIdle } from "./parent-wake.js";
 import { recordTurnsQueuedGauge, recordWorkerDeathRecoveryMetrics } from "../observability-metrics.js";
-import type { ControlActivityServices, ExpireSessionHumanInputInput, ExpireSessionHumanInputResult, ExpireSessionInteractionInterventionInput, ExpireSessionInteractionInterventionResult, PeekSessionWorkInput, FailSessionAttemptInput, FailSessionAttemptResult, SettleSessionInterruptionsInput, MarkSessionIdleInput, PersistSessionAttemptQuiescenceInput, ReconcileSessionAttemptQuiescenceInput, ReconcileSessionAttemptQuiescenceResult, RecoverDispatchInput, RecoverDispatchResult, RecoverEscapedMcpTimeoutInput, RecoverEscapedMcpTimeoutResult, SettleSessionInputWaitInput, SettleSessionInputWaitResult } from "./types.js";
+import type { ControlActivityServices, ExpireSessionHumanInputInput, ExpireSessionHumanInputResult, ExpireSessionInteractionInterventionInput, ExpireScheduledRunHumanWaitInput, ExpireScheduledRunHumanWaitResult, ExpireSessionInteractionInterventionResult, PeekSessionWorkInput, FailSessionAttemptInput, FailSessionAttemptResult, SettleSessionInterruptionsInput, MarkSessionIdleInput, PersistSessionAttemptQuiescenceInput, ReconcileSessionAttemptQuiescenceInput, ReconcileSessionAttemptQuiescenceResult, ReconcileSettledSessionAttemptInput, ReconcileSettledSessionAttemptResult, RecoverDispatchInput, RecoverDispatchResult, RecoverEscapedMcpTimeoutInput, RecoverEscapedMcpTimeoutResult, SettleSessionInputWaitInput, SettleSessionInputWaitResult } from "./types.js";
 export type SessionStateActivityOverrides = Partial<{
     settleSessionAttemptInterruptions: typeof settleSessionAttemptInterruptions;
     applySessionTurnSettlement: typeof applySessionTurnSettlement;
     enqueueSessionWorkflowWake: typeof enqueueSessionWorkflowWake;
     failSessionWorkBeforeAttemptClaim: typeof failSessionWorkBeforeAttemptClaim;
+    blockSessionWorkBeforeAttemptClaim: typeof blockSessionWorkBeforeAttemptClaim;
     requestSessionTurnRecovery: typeof requestSessionTurnRecovery;
     recoverSessionDispatch: typeof recoverSessionDispatch;
+    reconcileSettledSessionAttempt: typeof reconcileSettledSessionAttempt;
     reconcileSessionAttemptQuiescence: typeof reconcileSessionAttemptQuiescence;
+    reconcileCompletedSandboxSetup: typeof reconcileCompletedSandboxSetup;
     peekSessionWork: typeof peekSessionWorkDb;
     settleSessionInputWait: typeof settleSessionInputWaitDb;
     countQueuedTurns: typeof countQueuedTurns;
     getSessionAttemptActivityRef: typeof getSessionAttemptActivityRef;
     getSessionEvent: typeof getSessionEvent;
     getSessionTurnForAttempt: typeof getSessionTurnForAttempt;
+    getWorkspace: typeof getWorkspace;
     expireSessionHumanInputRequest: typeof expireSessionHumanInputRequest;
     expireSessionInteractionIntervention: typeof expireSessionInteractionInterventionDb;
+    expireScheduledRunHumanWait: typeof expireScheduledRunHumanWaitDb;
     requireSession: typeof requireSession;
     settleSessionIdleWithParentOutbox: typeof settleSessionIdleWithParentOutbox;
     markSessionAttemptQuiesced: typeof markSessionAttemptQuiesced;
@@ -36,11 +41,73 @@ export declare function createSessionStateActivities(services: () => Promise<Con
     }>;
     persistSessionAttemptQuiescence: (input: PersistSessionAttemptQuiescenceInput) => Promise<void>;
     reconcileSessionAttemptQuiescence: (input: ReconcileSessionAttemptQuiescenceInput) => Promise<ReconcileSessionAttemptQuiescenceResult>;
+    reconcileSettledSessionAttempt: (input: ReconcileSettledSessionAttemptInput) => Promise<ReconcileSettledSessionAttemptResult>;
     recoverDispatch: (input: RecoverDispatchInput) => Promise<RecoverDispatchResult>;
     recoverEscapedMcpTimeout: (input: RecoverEscapedMcpTimeoutInput) => Promise<RecoverEscapedMcpTimeoutResult>;
-    peekSessionWork: (input: PeekSessionWorkInput) => Promise<import("@opengeni/db").SessionWorkPeek>;
+    peekSessionWork: (input: PeekSessionWorkInput) => Promise<{
+        kind: "unavailable";
+    } | {
+        kind: "attempt-owned";
+        turnId: string;
+        attemptId: string;
+        executionGeneration: number;
+        activityRef: import("@opengeni/db").SessionAttemptActivityRef;
+    } | {
+        kind: "runnable";
+        admissionFence?: import("@opengeni/db").SessionAdmissionFence;
+    } | {
+        kind: "admission-blocked";
+        reason?: "sandbox_setup_outcome_unknown" | "sandbox_setup_recovery_exhausted";
+        ref?: import("@opengeni/db").SandboxSetupOutcomeUnknown | import("@opengeni/db").SandboxSetupRecoveryExhausted;
+    } | {
+        kind: "sandbox-lifecycle-wait";
+        ref: import("@opengeni/db").SandboxLifecycleWait;
+    } | {
+        kind: "approval-pending";
+        triggerEventId: string;
+        admissionFence?: import("@opengeni/db").SessionAdmissionFence;
+    } | {
+        kind: "approval-wait";
+        humanInputRequestId?: string;
+        interactionInterventionId?: string;
+        scheduledRunTimeout?: {
+            runId: string;
+            turnId: string;
+        };
+        expiresAt?: string;
+    } | {
+        kind: "capacity-wait";
+        ref: {
+            provider?: "codex" | "xai" | "claude";
+            waiterId: string;
+            generation: number;
+            nextCheckAt: string;
+            wakeRevision: number;
+        };
+    } | {
+        kind: "interruption-pending";
+        attemptId: string;
+    } | {
+        kind: "cancellation-wait";
+        attemptId: string;
+    } | {
+        kind: "input-wait";
+        disposition: "held" | "timeout" | "superseded";
+        waitTurnId: string;
+        deadlineAt: string;
+    } | {
+        kind: "idle";
+    } | {
+        kind: "attempt-owned";
+        turnId: string;
+        attemptId: string;
+        executionGeneration: number;
+        activityRef: import("@opengeni/db").SessionAttemptActivityRef;
+        ownerActivityState: "pending" | "settled" | "unknown";
+    }>;
     settleSessionInputWait: (input: SettleSessionInputWaitInput) => Promise<SettleSessionInputWaitResult>;
     expireSessionHumanInput: (input: ExpireSessionHumanInputInput) => Promise<ExpireSessionHumanInputResult>;
     expireSessionInteractionIntervention: (input: ExpireSessionInteractionInterventionInput) => Promise<ExpireSessionInteractionInterventionResult>;
+    expireScheduledRunHumanWait: (input: ExpireScheduledRunHumanWaitInput) => Promise<ExpireScheduledRunHumanWaitResult>;
     markSessionIdle: (input: MarkSessionIdleInput) => Promise<void>;
 };

package/dist/activities/types.d.ts

@@ -1,6 +1,6 @@
 import type { Settings } from "@opengeni/config";
 import type { ConnectionCredentialsPort, DocumentAuthorityKind, EntitlementsPort, KnowledgeSourceSyncRunSummary, ScheduledTaskTriggerType, TurnInitiator } from "@opengeni/contracts";
-import type { Database, SessionWorkflowWakeDeliveryResult } from "@opengeni/db";
+import type { Database, SessionWorkflowWakeDeliveryResult, SessionAdmissionFence } from "@opengeni/db";
 import type { DocumentServices } from "@opengeni/documents";
 import type { EventBus } from "@opengeni/events";
 import type { Observability } from "@opengeni/observability";
@@ -87,6 +87,11 @@ export type SharedActivityServices = {
 export type ControlActivityServices = SharedActivityServices;
 /** Turn workers own the model loop and never construct document parsers. */
 export type TurnActivityServices = SharedActivityServices & {
+    /** Host-owned containment: stop polling and checkpoint peer turns before exit.
+     * Bare activity embedders must provide their own worker lifecycle edge. */
+    requestWorkerDrain: () => void;
+    /** Deterministic test clock for the cleanup-only monitor. */
+    turnFinalizationTimeoutMs?: number | undefined;
     runtime: OpenGeniRuntime;
     /** Provider-free test/profiling seam; production injects the real runtime summarizer. */
     summarizeContextForCompaction: typeof import("@opengeni/runtime").summarizeForCompaction;
@@ -97,7 +102,7 @@ export type ActivityServices = ControlActivityServices & TurnActivityServices &
 };
 export type CodexCapacityWaitRef = {
     /** Absent only for Temporal histories written before provider-tagged waits. */
-    provider?: "codex" | "xai";
+    provider?: "codex" | "xai" | "claude";
     waiterId: string;
     generation: number;
     nextCheckAt: string;
@@ -118,7 +123,7 @@ export type ReconcileCodexCapacityWaitInput = {
     generation: number;
     cause: "timer" | "signal" | "queue" | "recovery";
     /** Absent only for Codex waits and pre-provider-tagged workflow histories. */
-    provider?: "codex" | "xai";
+    provider?: "codex" | "xai" | "claude";
 };
 export type ReconcileCodexCapacityWaitResult = ({
     action: "waiting";
@@ -174,6 +179,20 @@ export type ReconcileSessionAttemptQuiescenceInput = {
 export type ReconcileSessionAttemptQuiescenceResult = {
     action: "quiesced" | "pending" | "stale";
 };
+export type ReconcileSettledSessionAttemptInput = {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    attemptId: string;
+    executionGeneration: number;
+    workflowId: string;
+    workflowRunId: string;
+    activityId: string;
+};
+export type ReconcileSettledSessionAttemptResult = {
+    action: "recovering" | "exceeded" | "pending" | "stale";
+};
 export type FailSessionAttemptInput = {
     accountId: string;
     workspaceId: string;
@@ -191,6 +210,7 @@ export type FailSessionAttemptInput = {
      * committed claim discovered by the control lane can recover the exact
      * attempt instead of terminally failing it. */
     preClaimFailure?: PreClaimFailureDetail;
+    admissionFence?: SessionAdmissionFence;
     /** Added in v4. A claimed attempt that lost operational database access
      * before turn-start completion carries its exact immutable turn identity so
      * the DB-only control lane can recover it instead of terminally failing it. */
@@ -201,6 +221,8 @@ export type FailSessionAttemptInput = {
     error?: string;
 };
 export type FailSessionAttemptResult = {
+    action: "blocked";
+} | {
     action: "failed";
 } | {
     action: "recovering";
@@ -211,10 +233,13 @@ export type FailSessionAttemptResult = {
 } | {
     action: "stale";
 };
-export type PreClaimFailureDisposition = "retryable" | "permanent";
+export type PreClaimFailureDisposition = "retryable" | "permanent" | "blocked";
 export type PreClaimFailureDetail = {
     disposition: PreClaimFailureDisposition;
     code: "db_deadlock" | "db_serialization_failure" | "db_failure" | "claim_invariant";
+    sqlState?: string | null;
+    reason?: "database_claim_rejected" | "initiator_membership_required" | "personal_resource_grant_required";
+    retryPolicy?: "explicit_recheck";
 };
 export declare const PRE_CLAIM_FAILURE_TYPE = "OpenGeniPreClaimFailure";
 export declare const PRE_CLAIM_FAILURE_MESSAGE = "Agent turn admission failed before attempt claim.";
@@ -229,6 +254,10 @@ export type PostClaimDatabaseRecoveryDetail = {
     providerRecoveryCount?: number;
     /** Safe classified provider cause paired with providerRecoveryCount. */
     providerFailureCode?: string;
+    /** Persist the no-replay setup marker, not a new provider/setup attempt. */
+    sandboxSetupOutcomeUnknown?: true;
+    /** Preserve the exhausted budget for a command proven not dispatched. */
+    sandboxSetupRecoveryExhausted?: true;
 };
 export declare const POST_CLAIM_DATABASE_RECOVERY_FAILURE_TYPE = "OpenGeniPostClaimDatabaseRecovery";
 export declare const POST_CLAIM_DATABASE_RECOVERY_FAILURE_MESSAGE = "Agent turn database recovery required after attempt claim.";
@@ -273,6 +302,9 @@ export type RecoverEscapedMcpTimeoutResult = {
 export type PeekSessionWorkInput = {
     workspaceId: string;
     sessionId: string;
+    includeAdmissionFence?: boolean;
+    /** Versioned workflow observer opt-in, never a caller authorization grant. */
+    observerAccountId?: string;
 };
 export type SettleSessionInputWaitInput = {
     accountId: string;
@@ -302,6 +334,16 @@ export type ExpireSessionInteractionInterventionInput = {
 export type ExpireSessionInteractionInterventionResult = {
     action: "expired" | "stale" | "not_found";
 };
+export type ExpireScheduledRunHumanWaitInput = {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    runId: string;
+};
+export type ExpireScheduledRunHumanWaitResult = {
+    action: "expired" | "stale" | "not_found";
+};
 export type MarkSessionIdleInput = {
     workspaceId: string;
     sessionId: string;
@@ -324,17 +366,24 @@ export type DispatchScheduledTaskRunInput = {
     triggerType: Extract<ScheduledTaskTriggerType, "scheduled">;
     agentRunUsageIdempotencyKey?: never;
     initiator?: never;
+    credentialRestriction?: never;
 } | {
     triggerType: Extract<ScheduledTaskTriggerType, "manual" | "initial" | "provider_event" | "retry" | "repair">;
     agentRunUsageIdempotencyKey: string;
     /** Exact identity used by the API-side charge for this same trigger. */
     initiator: TurnInitiator;
+    /** Trusted API-side caller ceiling for this occurrence, not the schedule. */
+    credentialRestriction?: "developer_setup";
 });
 export type DispatchScheduledTaskRunResult = {
     action: "deleted";
 } | {
     action: "blocked";
-    reason: "insufficient_credits" | "monthly_model_cost_limit" | "monthly_agent_run_limit" | "malformed_manual_trigger" | "scheduled_task_paused" | "scheduled_authority_exhausted" | "scheduled_run_terminal" | "scheduled_execution_unrepresentable" | "knowledge_source_paused" | "legacy_source_schedule_requires_migration" | "incident_preflight_metadata_missing" | "incident_responder_under_capable" | "incident_data_source_unsuitable";
+    runId?: string;
+    diagnostic?: import("@opengeni/contracts").ConnectionAccountSelectionDiagnostic;
+    /** Present when the occurrence was refused as a visible run receipt. */
+    refusal?: import("@opengeni/contracts").ScheduledTaskAdmissionRefusal;
+    reason: "insufficient_credits" | "allowance_exhausted" | "monthly_model_cost_limit" | "monthly_agent_run_limit" | "malformed_manual_trigger" | "scheduled_task_paused" | "scheduled_authority_exhausted" | "scheduled_run_terminal" | "scheduled_execution_unrepresentable" | "connection_account_unavailable" | "scheduled_authority_unavailable" | "machine_target_unavailable" | "machine_enrollment_inactive" | "variable_set_unavailable" | "rig_version_unavailable" | "knowledge_source_paused" | "legacy_source_schedule_requires_migration" | "atlassian_native_retired" | "incident_preflight_metadata_missing" | "incident_responder_under_capable" | "incident_data_source_unsuitable";
 } | {
     action: "start" | "signal";
     accountId: string;
@@ -427,6 +476,6 @@ type ClaimedRunAgentTurnResult = {
 };
 export type RunAgentTurnResult = ClaimedRunAgentTurnResult | {
     status: "unclaimed";
-    reason: "gate-closed" | "no-work" | "stale-approval" | "control-pending";
+    reason: "gate-closed" | "no-work" | "stale-approval" | "control-pending" | "dispatch-expired";
 };
 export {};

package/dist/activities/workspace-capture.d.ts

@@ -108,6 +108,8 @@ export declare function captureWhileIdle(input: {
  * to release() regardless.
  */
 export declare function captureWorkspaceRevision(input: CaptureWorkspaceRevisionInput): Promise<void>;
+/** Count one committed logical capture and observe its end-to-end duration. */
+export declare function recordWorkspaceCaptureCompleted(observability: Pick<Observability, "incrementCounter" | "observeHistogram">, durationMs: number): void;
 /**
  * sha256 over the CHANGE SURFACE only — per-file (path, status, hash, deleted,
  * tooLarge), exact HEAD identity, the working diff summary, and exact committed

package/dist/activities/workspace-credential-provider.d.ts

@@ -0,0 +1,46 @@
+import { type Settings } from "@opengeni/config";
+import { CredentialProviderResponse, type CredentialProviderRequest, type RunCredentialsRequest, type RunCredentialsResolution } from "@opengeni/contracts";
+import { resolveWorkspaceCredentialProvider, resolveInitiatingHuman, type Database } from "@opengeni/db";
+import { pinnedFetch } from "@opengeni/network";
+export declare const GIT_CREDENTIALS_FILE = "git/credentials";
+export declare const GIT_CREDENTIALS_FILE_ENV = "OPENGENI_GIT_CREDENTIALS_FILE";
+export declare class CredentialProviderError extends Error {
+    constructor(message: string);
+}
+export type WorkspaceRunCredentialResolver = (input: RunCredentialsRequest) => Promise<RunCredentialsResolution>;
+type ProviderOk = Extract<CredentialProviderResponse, {
+    status: "ok";
+}>;
+/**
+ * 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 declare function withGitCredentialHelper(response: ProviderOk): ProviderOk;
+export declare function credentialProviderRequestBody(input: RunCredentialsRequest, initiatingHumanSubjectId: string | null, initiatingHuman?: CredentialProviderRequest["initiatingHuman"], selection?: Pick<CredentialProviderRequest, "lane" | "mcpServers">): CredentialProviderRequest;
+export declare function toRunCredentialsResolution(response: CredentialProviderResponse, scope: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+}): RunCredentialsResolution;
+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 declare function workspaceCredentialProviderResolver(db: Database, settings: Settings, scope: {
+    accountId: string;
+    workspaceId: string;
+}, initiatingHumanSubjectId: string | null, deps?: WorkspaceCredentialProviderDeps): Promise<WorkspaceRunCredentialResolver | null>;
+export {};